Merge pull request #154 from lorenzwalthert/tidyup

Finalize function documentation (#154).

Author: lorenzwalthert

R/nested.R

@@ -7,23 +7,6 @@
 #' @return A nested parse table. Apart from the columns provided by
 #'   `utils::getParseData()`, a column "short" with the first five characters of
 #'   "text" is added, the nested subtibbles are in column "child".
-#' TODO:
-#' - Implement enhance_parse_data_nested()
-#'     - Walk tree defined by `child`, compute whitespace information
-#'     - Store indention depth in a separate column, unaffected by
-#'       inter-token space
-#' - Implement compute_parse_data_nested_with_ws() as
-#'   compute_parse_data_nested() + enhance_parse_data_nested()
-#' - Implement serialization of nested parse data
-#' - Use compute_parse_data_nested_with_ws() instead of
-#'   compute_parse_data_flat_enhanced()
-#' - Perform all transformations on hierarchical structure
-#'     - Compute text for a sub-element
-#' - Compute indentation
-#'     - Braces
-#'     - Function calls
-#'     - Function definitions
-#' - Remove `includeText = TRUE`
 compute_parse_data_nested <- function(text) {
   parse_data <- tokenize(text) %>%
     add_terminal_token_before() %>%
@@ -150,7 +133,7 @@ nest_parse_data <- function(pd_flat) {
 
 #' Combine child and internal child
 #'
-#' binds two parse tables together and arranges them so that the tokens are in
+#' Binds two parse tables together and arranges them so that the tokens are in
 #'   the correct order.
 #' @param child A parse table or `NULL`.
 #' @param internal_child A parse table or `NULL`.

R/style_guides.R

@@ -1,11 +1,28 @@
+#' Style guides
+#'
+#' Format code according to a style guide. Style guides are the input to the
+#' argument `style` in [style_file()] and friends.
+#' The available style guides are:
+#' * the tidyverse style guide (see [tidyverse_style()]).
+#' @name style_guides
+NULL
+
+
 #' The tidyverse style
+#'
+#' Style code according to the tidyverse style guide.
 #' @param scope The extent of manipulation. Can range from "none" (least
 #'   invasive) to "token" (most invasive). See 'Details'. This argument is a
 #'   vector of length one.
 #' @param indent_by How many spaces of indention should be inserted after
 #'   operators such as '('.
 #' @param strict A logical value indicating whether a set of strict
-#'   or not so strict transformer functions should be returned.
+#'   or not so strict transformer functions should be returned. Compare the
+#'   functions returned with or without `strict = TRUE`. For example,
+#'   `strict = TRUE` means force *one* space e.g. after "," and *one* line break
+#'   e.g. after a closing curly brace. `strict = FALSE` means to set spaces and
+#'   line breaks to one if there is none and leave the code untouched otherwise.
+#'   See 'Examples'.
 #' @param start_comments_with_one_space Whether or not comments should start
 #'   with only one space (see [start_comments_with_space()]).
 #' @details The following options for `scope` are available.
@@ -22,6 +39,11 @@
 #' As it becomes clear from this description, more invasive operations can only
 #' be performed if all less invasive operations are performed too.
 #' @family obtain transformers
+#' @family style_guides
+#' @examples
+#' style_text("call( 1)", style = tidyverse_style, scope = "spaces")
+#' style_text(c("ab <- 3", "a  <-3"), strict = FALSE) # keeps alignment of "<-"
+#' style_text(c("ab <- 3", "a  <-3"), strict = TRUE) # drops alignment of "<-"
 #' @importFrom purrr partial
 #' @export
 tidyverse_style <- function(scope = "tokens",

R/ws.R

@@ -12,10 +12,15 @@ NULL
 #'
 #' @param pkg Path to a (subdirectory of an) R package.
 #' @param ... Passed on to the `style` function.
-#' @param style A function that creates a style guide to use, by default
-#'   [tidyverse_style()] (without the parentheses). Will not be used further
-#'   except to construct the argument `transformers`.
+#' @param style The unquoted name of a style guide to use. Will not be used
+#'   further except to construct the argument `transformers`. See
+#'   [style_guides()] for details.
 #' @param transformers A set of transformer functions.
+#' @family stylers
+#' @examples
+#' \dontrun{
+#' style_pkg()
+#' }
 #' @export
 #' @family stylers
 style_pkg <- function(pkg = ".",
@@ -45,10 +50,14 @@ prettify_local <- function(transformers) {
 
 #' Style a string
 #'
-#' Styles a character vector
+#' Styles a character vector. Each element of the character vector corresponds
+#' to one line of code.
 #' @param text A character vector with text to style.
 #' @inheritParams style_pkg
 #' @family stylers
+#' @examples
+#' style_text("call( 1)")
+#' style_text("1    + 1", strict = FALSE)
 #' @export
 style_text <- function(text,
                        ...,