Merge pull request #958 from IndrajeetPatil/edits_to_vignettes

docs: edits to vignettes

Author: lorenzwalthert

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).

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.

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

R/ui-styling.R

@@ -1,4 +1,4 @@
-#' @api
+#' @keywords api
 #' @import tibble
 #' @importFrom magrittr %>%
 NULL

inst/WORDLIST

@@ -85,7 +85,7 @@ ifelse
 impl
 infinitively
 initializer
-innode
+inode
 integrations
 interaces
 invasiveness

man/cache_clear.Rd

@@ -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.
 

man/cache_info.Rd

@@ -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.