diff --git a/NEWS.md b/NEWS.md index 693d9ccfe..2a2ba388a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -35,6 +35,7 @@ editor_options: - Old (and outdated) vignettes have been removed (\@IndrajeetPatil, #955). To access them, do `git checkout v1.0.0`. - Upgrade testing infra to testthat 3e (\@IndrajeetPatil, #949). +- Minor improvements to the documentation (\@IndrajeetPatil, #958). - All (R)md files in this project's source code are now formatted with default pandoc markdown formatter. This conversion is required when using the visual mode in RStudio (#941). diff --git a/R/styler.R b/R/styler.R index 750fd71b3..2127443d2 100644 --- a/R/styler.R +++ b/R/styler.R @@ -1,11 +1,12 @@ #' Non-invasive pretty printing of R code #' -#' styler allows you to format .R files, packages or entire R source trees +#' styler allows you to format `.R`, `.Rmd`, `.Rmarkdown` and/or +#' `.qmd`, `.Rnw` files, R packages, or entire R source trees #' according to a style guide. #' The following functions can be used for styling: #' * [style_text()] to style a character vector. -#' * [style_file()] to style a single .R file. -#' * [style_dir()] to style all .R files in a directory. +#' * [style_file()] to style a single file. +#' * [style_dir()] to style all files in a directory. #' * [style_pkg()] to style the source files of an R package. #' * [styler_addins] (RStudio Addins) to style either selected code or the #' active file. diff --git a/R/ui-caching.R b/R/ui-caching.R index 086ef3bec..7c23bf706 100644 --- a/R/ui-caching.R +++ b/R/ui-caching.R @@ -8,7 +8,7 @@ #' `NULL`, the option "styler.cache_name" is considered which defaults to #' the version of styler used. #' @details -#' Each version of styler has it's own cache by default, because styling is +#' Each version of styler has its own cache by default, because styling is #' potentially different with different versions of styler. #' @param ask Whether or not to interactively ask the user again. #' @family cache managers @@ -61,7 +61,7 @@ NULL #' #' Gives information about the cache. Note that the size consumed by the cache #' will always be displayed as zero because all the cache does is creating an -#' empty file of size 0 bytes for every cached expression. The innode is +#' empty file of size 0 bytes for every cached expression. The inode is #' excluded from this displayed size but negligible. #' @param cache_name The name of the cache for which to show details. If #' `NULL`, the active cache is used. If none is active the cache corresponding diff --git a/R/ui-styling.R b/R/ui-styling.R index 36bac33f0..50c69875c 100644 --- a/R/ui-styling.R +++ b/R/ui-styling.R @@ -1,4 +1,4 @@ -#' @api +#' @keywords api #' @import tibble #' @importFrom magrittr %>% NULL diff --git a/inst/WORDLIST b/inst/WORDLIST index 1df7934e9..92d9706b8 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -85,7 +85,7 @@ ifelse impl infinitively initializer -innode +inode integrations interaces invasiveness diff --git a/man/cache_clear.Rd b/man/cache_clear.Rd index cdbcf8d20..3a97a3bff 100644 --- a/man/cache_clear.Rd +++ b/man/cache_clear.Rd @@ -20,7 +20,7 @@ on your file system) won't be deleted, but it will be empty after calling \code{cache_clear}. } \details{ -Each version of styler has it's own cache by default, because styling is +Each version of styler has its own cache by default, because styling is potentially different with different versions of styler. } \seealso{ diff --git a/man/cache_info.Rd b/man/cache_info.Rd index 16fe141e6..363336316 100644 --- a/man/cache_info.Rd +++ b/man/cache_info.Rd @@ -18,7 +18,7 @@ both.} \description{ Gives information about the cache. Note that the size consumed by the cache will always be displayed as zero because all the cache does is creating an -empty file of size 0 bytes for every cached expression. The innode is +empty file of size 0 bytes for every cached expression. The inode is excluded from this displayed size but negligible. } \seealso{ diff --git a/man/styler-package.Rd b/man/styler-package.Rd index 5cd124905..4a695f27c 100644 --- a/man/styler-package.Rd +++ b/man/styler-package.Rd @@ -6,13 +6,14 @@ \alias{styler-package} \title{Non-invasive pretty printing of R code} \description{ -styler allows you to format .R files, packages or entire R source trees +styler allows you to format \code{.R}, \code{.Rmd}, \code{.Rmarkdown} and/or +\code{.qmd}, \code{.Rnw} files, R packages, or entire R source trees according to a style guide. The following functions can be used for styling: \itemize{ \item \code{\link[=style_text]{style_text()}} to style a character vector. -\item \code{\link[=style_file]{style_file()}} to style a single .R file. -\item \code{\link[=style_dir]{style_dir()}} to style all .R files in a directory. +\item \code{\link[=style_file]{style_file()}} to style a single file. +\item \code{\link[=style_dir]{style_dir()}} to style all files in a directory. \item \code{\link[=style_pkg]{style_pkg()}} to style the source files of an R package. \item \link{styler_addins} (RStudio Addins) to style either selected code or the active file. diff --git a/vignettes/caching.Rmd b/vignettes/caching.Rmd index a38bd5728..b5f9a7553 100644 --- a/vignettes/caching.Rmd +++ b/vignettes/caching.Rmd @@ -18,11 +18,11 @@ knitr::opts_chunk$set( library(styler) ``` -This is a developer vignette to explain how caching works and what we learned on the way. To use the caching feature, please have a look at the README. +This is a developer vignette to explain how caching works and what we learned on the way. The main caching features were implemented in the following two pull requests: -- #538: Implemented simple caching and utilities for managing caches. Input text is styled as a whole and added to the cache afterwards. This makes most sense given that the very same expression will probably never be passed to styler, unless it is already compliant with the style guide. Apart from the (negligible) innode, caching text has a memory cost of 0. Speed boosts only result if the whole text passed to styler is compliant to the style guide in use. Changing one line in a file with hundreds of lines means each line will be styled again. This is a major drawback and makes the cache only useful for a use with a pre-commit framework (the initial motivation) or when functions like `style_pkg()` are run often and most files were not changed. +- #538: Implemented simple caching and utilities for managing caches. Input text is styled as a whole and added to the cache afterwards. This makes most sense given that the very same expression will probably never be passed to styler, unless it is already compliant with the style guide. Apart from the (negligible) inode, caching text has a memory cost of 0. Speed boosts only result if the whole text passed to styler is compliant to the style guide in use. Changing one line in a file with hundreds of lines means each line will be styled again. This is a major drawback and makes the cache only useful for a use with a pre-commit framework (the initial motivation) or when functions like `style_pkg()` are run often and most files were not changed. - #578: Adds a second layer of caching by caching top-level expressions individually. This will bring speed boosts to the situation where very little is changed but there are many top-level expressions. Hence, changing one line in a big file will invalidate the cache for the expression the line is part of, i.e. when changing `x <- 2` to `x = 2` below, styler will have to restyle the function definition, but not `another(call)` and all other expressions that were not changed. diff --git a/vignettes/customizing_styler.Rmd b/vignettes/customizing_styler.Rmd index 214c6c5ab..7ec808c8b 100644 --- a/vignettes/customizing_styler.Rmd +++ b/vignettes/customizing_styler.Rmd @@ -13,7 +13,7 @@ This vignette provides a high-level overview of how styler works and how you can There are three major steps that styler performs in order to style code: -1. Create an abstract syntax tree (AST) from `utils::getParseData()` that contains positional information for every token. We call this a nested parse table. You can learn more about how exactly this is done in the vignettes "Data Structures" and "Manipulating the nested parse table". +1. Create an abstract syntax tree (AST) from `utils::getParseData()` that contains positional information for every token. We call this a nested parse table. 2. Apply transformer functions at each level of the nested parse table. We use a visitor approach, i.e. a function that takes functions as arguments and applies them to every level of nesting. You can find out more about it on the help file for `visit()`. Note that the function is not exported by styler. The visitor will take care of applying the functions on every level of nesting - and we can supply transformer functions that operate on one level of nesting. In the sequel, we use the term *nest* to refer to such a parse table at one level of nesting. A *nest* always represents a complete expression. Before we apply the transformers, we have to initialize two columns `lag_newlines` and `spaces`, which contain the number of line breaks before the token and the number of spaces after the token. These will be the columns that most of our transformer functions will modify. diff --git a/vignettes/remove_rules.Rmd b/vignettes/remove_rules.Rmd index 7179fa1de..11c79ae63 100644 --- a/vignettes/remove_rules.Rmd +++ b/vignettes/remove_rules.Rmd @@ -41,7 +41,7 @@ are multiple ways: *remove* a rule, I have good news for you: There is a quick way to do it. And that's what the remainder of this vignette focuses on. -Once you are happy with your style guide, you might ant to have a look at how +Once you are happy with your style guide, you might want to have a look at how to distribute it, which is described in `vignette("distribute_custom_style_guides")`. diff --git a/vignettes/styler.Rmd b/vignettes/styler.Rmd index aa93a8eaa..c4a336934 100644 --- a/vignettes/styler.Rmd +++ b/vignettes/styler.Rmd @@ -199,7 +199,7 @@ style_text( ### Custom style guides -These verse some (not all) configurations exposed in `style_file()` and friends as well as `tidyverse_style()`. If the above did not give you the flexibility you hoped for, your can create your own style guide and customize styler even further: +These were some (not all) configurations exposed in `style_file()` and friends as well as `tidyverse_style()`. If the above did not give you the flexibility you hoped for, your can create your own style guide and customize styler even further: - either by removing rules from the tidyverse style guide as described in `vignette("remove_rules")`. - or by creating your own style guide from scratch as described in `vignette("customizing_styler")`. diff --git a/vignettes/third-party-integrations.Rmd b/vignettes/third-party-integrations.Rmd index 8925ba419..679ad363f 100644 --- a/vignettes/third-party-integrations.Rmd +++ b/vignettes/third-party-integrations.Rmd @@ -34,7 +34,7 @@ styler functionality is available in other tools, most notably - in the *format-all* command for Emacs in [emacs-format-all-the-code](https://github.com/lassik/emacs-format-all-the-code). -- As a [Jupyterlab code formatter](https://jupyterlab-code-formatter.readthedocs.io/en/latest/installation.html#r-code-formatters). +- As a [Jupyterlab code formatter](https://ryantam626.github.io/jupyterlab_code_formatter/index.html). - for pretty-printing [drake](https://github.com/ropensci/drake) workflow data frames with `drake::drake_plan_source()`.