better documentation

Author: lorenzwalthert

R/ui-caching.R

@@ -23,15 +23,42 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) {
 
 #' Remember the past to be quicker in the future
 #'
+#' Caching makes styler faster on repeated styling. It does not cache input
+#' but output code. That means if you style code that already complies to a
+#' style guide and you have previously styled that code, it will be quicker.
+#' Code is cached by expression and the cache is shared across all APIs.
+#'
+#' @section Setup:
 #' styler by default uses caching. It may prompt you to install the R package
 #' `R.cache` the first time you want to use it. R.cache will also ask you to let
 #' it create a permanent cache on your file system that styler will use.
 #' This is needed if you want to cache across R sessions and not just within.
+#'
+#' @section Non-interactive use:
+#' Note that if you have never authorized `{R.cache}` to create the cache in a
+#' permenent directory, it wil build the cache in a temporary directory. To
+#' create a permenent cache, just open an interactive R session and type
+#' `cache_info()`. You can see under `Location:` if a permanent directory is
+#' used and if not, `{R.cache}` will ask you to create one.
+#'
+#' @section Invalidation:
 #' The cache is specific to a version of styler by default, because different
 #' versions potentially format code differently. This means after upgrading
 #' styler or a style guide you use, the cache will be re-built.
+#'
+#' @section Manage the cache:
 #' See [cache_info()],
-#' [cache_activate()], [cache_clear()] for utilities to manage the cache.
+#' [cache_activate()], [cache_clear()] for utilities to manage the cache. Since
+#' we leverage `{R.cache}` to manage the cache, you can also use any `{R.cache}`
+#' functionality to manipulate it.
+#'
+#' @section Using a cache for styler in CI/CD:
+#' If you want to set up caching in a CI/CD pipeline, we suggest to set the
+#' `{R.cache}` root path to a directory for which you have the cache enabled.
+#' The former can be done with `R.cache::setCacheRootPath("/path/to/cache")`,
+#' the latter can often be set in config files of CI/CD tools, e.g. see the
+#' the [Travis documentation on caching](https://docs.travis-ci.com/user/caching).
+#'
 #' @name caching
 NULL