turn verbose warning into slick messsage and move info to docs

Author: lorenzwalthert

DESCRIPTION

@@ -53,7 +53,7 @@ Roxygen: list(markdown = TRUE, roclets = c( "rd", "namespace", "collate",
     if (rlang::is_installed("pkgapi")) "pkgapi::api_roclet" else {
     warning("Please install r-lib/pkgapi to make sure the file API is kept
     up to date"); NULL}))
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.2
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Collate: 

R/ui-caching.R

@@ -23,9 +23,25 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) {
 #' Remember the past to be quicker in the future
 #'
 #' Caching makes styler faster on repeated styling and is shared across all APIs
-#' (e.g. `style_text()` and Addin).
-#' That means if you style code that already complies to a
-#' style guide and you have previously styled that code, it will be quicker.
+#' (e.g. `style_text()` and Addin). That means if you style code that already
+#' complies to a style guide and you have previously styled that code, it will
+#' be quicker.
+#'
+#' @section Configuring the cache:
+#'
+#' To comply with the CRAN policy, \{styler\} will by default clean up cache files
+#' that are older than 6 days. This implies that you loose the benefit of the cache
+#' for the files not styled in the last 6 days. You can set the R option
+#' `styler.cache_root` explicitly, (e.g. in your `.Rprofile` with
+#' [usethis::edit_r_profile()]) to
+#'
+#' * confirm the default and silence the message with
+#'   `options(styler.cache_root = "styler")`.
+#'
+#' * opt for an indefinitely long-living cache by setting the option to something
+#'   else (we recommend `options(styler.cache_root = "styler-perm")`, which is
+#'   also used by pre-commit).
+#'
 #' @section Manage the cache:
 #' See [cache_info()],[cache_activate()] or [cache_clear()] for utilities to
 #' manage the cache. You can deactivate it altogether with [cache_deactivate()].
@@ -47,6 +63,11 @@ cache_clear <- function(cache_name = NULL, ask = TRUE) {
 #' which is why it takes zero space on disk (the cache is a directory with
 #' empty files which have the hash of output code as name).
 #'
+#' The cache literally takes zero space on your disk, only the inode, and you
+#' can always manually clean up with [cache_clear()] or just go to the
+#' directory where the cache lives (find it with [cache_info()]) and manually
+#' delete files.
+#'
 #' @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.

R/zzz.R

@@ -31,21 +31,11 @@ ask_to_switch_to_non_default_cache_root <- function(ask = interactive()) {
   }
 }
 
+
 ask_to_switch_to_non_default_cache_root_impl <- function() {
-  rlang::warn(paste0(
-    "The R option `styler.cache_root` is not set, which means the cache ",
-    "will get cleaned up after 6 days (and repeated styling will be slower).",
-    " To keep cache files longer, set ",
-    "the option to location within the {R.cache} cache where you want to ",
-    "store the cache, e.g. `\"styler-perm\"`.\n\n",
-    "options(styler.cache_root = \"styler-perm\")\n\n",
-    "in your .Rprofile. Note that the cache literally ",
-    "takes zero space on your disk, only the inode, and you can always ",
-    "manually clean up with `styler::cache_clear()`, and if you update the ",
-    "{styler} package, the cache is removed in any case. To ignore this ",
-    "message in the future, set the default explictly to \"styler\" with\n\n",
-    "options(styler.cache_root = \"styler\")\n\nin your `.Rprofile`. This ",
-    "message will only be displayed once in a while.\n"
+  rlang::inform(paste0(
+    "{styler} cache is cleared after 6 days. ",
+    "See `?styler::caching` to configure differently or silence this message."
   ))
 }
 

man/caching.Rd

@@ -512,9 +512,9 @@ test_that("Can properly determine style_after_saving", {
 test_that("Can display warning on unset styler cache", {
   withr::local_options(styler.cache_root = NULL)
   withr::local_seed(7)
-  expect_warning(
+  expect_message(
     ask_to_switch_to_non_default_cache_root(ask = TRUE),
-    'options(styler.cache_root = "styler-perm")',
+    "See `?styler::caching`",
     fixed = TRUE
   )
 })