document local vs global cassette options in config

R/configuration.R

@@ -1,74 +1,86 @@
-#' Configuration
+#' Global Configuration Options
 #'
-#' Optional settings to customize vcr's default behavior.
+#' Configurable options that define vcr's default behavior.
 #'
 #' @param ... configuration settings used to override defaults. See below for a
 #'   complete list of valid arguments.
 #'
 #' @section Configurable settings:
 #'
-#' ## Casstte options
+#' ## vcr options
 #'
-#' - `dir` Cassette directory
-#' - `record` (character) One of 'all', 'none', 'new_episodes', or 'once'.
-#' See [recording]
-#' - `match_requests_on` vector of matchers. Default: (`method`, `uri`)
-#' See [request-matching] for details.
-#' - `cassettes` (list) don't use
-#' - `linked_context` (logical) linked context
+#' ### File locations
 #'
-#' ## Recordings
-#'
-#' - `serialize_with`: (character) only option is "yaml"
-#' - `persist_with` (character) only option is "FileSystem"
-#' - `uri_parser` the uri parser, default: [crul::url_parse()]
-#' - `preserve_exact_body_bytes` (logical) preserve exact body bytes for
-#' - `turned_off` (logical) VCR is turned on by default. Default:
-#' `FALSE`
-#' - `re_record_interval` (numeric) When given, the cassette will be
-#' re-recorded at the given interval, in seconds.
-#' - `clean_outdated_http_interactions` (logical) Should outdated interactions
-#' be recorded back to file. Default: `FALSE`
+#' - `dir` Cassette directory
 #' - `write_disk_path` (character) path to write files to
 #' for any requests that write responses to disk. by default this parameter
 #' is `NULL`. For testing a package, you'll probably want this path to
 #' be in your `tests/` directory, perhaps next to your cassettes
 #' directory, e.g., where your cassettes are in `tests/fixtures`, your
 #' files from requests that write to disk are in `tests/files`
 #'
-#' ## Connectivity
+#' ### Contexts
 #'
+#' - `turned_off` (logical) VCR is turned on by default. Default:
+#' `FALSE`
 #' - `allow_unused_http_interactions` (logical) Default: `TRUE`
 #' - `allow_http_connections_when_no_cassette` (logical) Determines how vcr
 #' treats HTTP requests that are made when no vcr cassette is in use. When
 #' `TRUE`, requests made when there is no vcr cassette in use will be allowed.
 #' When `FALSE` (default), an [UnhandledHTTPRequestError] error will be raised
 #' for any HTTP request made when there is no cassette in use
 #'
-#' ## Logging
-#'
-#' - `log` (logical) should we log important vcr things? Default: `FALSE`
-#' - `log_opts` (list) Additional logging options. Options include:
-#'   - file: one of a file path to log to or "console"
-#'   - log_prefix: default: "Cassette". We insert the cassette name after
-#'     that prefix, then the rest of the message
-#'   - More to come...
-#'
-#' ## Filtering
+#' ### Filtering
 #'
 #' - `ignore_hosts` (character) Vector of hosts to ignore. e.g., localhost, or
 #' google.com. These hosts are ignored and real HTTP requests allowed to go
 #' through
 #' - `ignore_localhost` (logical) Default: `FALSE`
 #' - `ignore_request` List of requests to ignore. NOT USED RIGHT NOW, sorry
-#' - `filter_sensitive_data` (list) named list of values to replace. format
-#' is: `list(thing_to_replace_it_with = thing_to_replace)`. We replace all
-#' instances of `thing_to_replace` with `thing_to_replace_it_with`. Before
-#' recording (writing to a cassette) we do the replacement and then when
-#' reading from the cassette we do the reverse replacement to get back
-#' to the real data. Before record replacement happens in internal
-#' function `write_interactions()`, while before playback replacement
-#' happens in internal function `YAML$deserialize_path()`
+#' - `filter_sensitive_data` named list of values to replace. Format is:
+#'   ```
+#'   list(thing_to_replace_it_with = thing_to_replace)
+#'   ```
+#'   We replace all instances of `thing_to_replace` with
+#' `thing_to_replace_it_with`. Before recording (writing to a cassette) we do
+#' the replacement and then when reading from the cassette we do the reverse
+#' replacement to get back to the real data. Before record replacement happens
+#' in internal function `write_interactions()`, while before playback
+#' replacement happens in internal function `YAML$deserialize_path()`
+#'
+#' ### Internals
+#'
+#' - `cassettes` (list) don't use
+#' - `linked_context` (logical) linked context
+#' - `uri_parser` the uri parser, default: [crul::url_parse()]
+#'
+#' ### Logging
+#'
+#' - `log` (logical) should we log important vcr things? Default: `FALSE`
+#' - `log_opts` (list) Additional logging options:
+#'   - `file` either `"console"` or a file path to log to
+#'   - `log_prefix` default: "Cassette". We insert the cassette name after
+#'     that prefix, then the rest of the message.
+#'   - More to come...
+#'
+#' ## Cassette Options
+#'
+#' These settings can be configured globally, using `vcr_configure()`, or
+#' locally, using either `use_cassette()` or `insert_cassette()`. Global
+#' settings are applied to *all* cassettes but are overridden by settings
+#' defined locally for individuall cassettes.
+#'
+#' - `record` (character) One of 'all', 'none', 'new_episodes', or 'once'.
+#' See [recording]
+#' - `match_requests_on` vector of matchers. Default: (`method`, `uri`)
+#' See [request-matching] for details.
+#' - `serialize_with`: (character) only option is "yaml"
+#' - `persist_with` (character) only option is "FileSystem"
+#' - `preserve_exact_body_bytes` (logical) preserve exact body bytes for
+#' - `re_record_interval` (numeric) When given, the cassette will be
+#' re-recorded at the given interval, in seconds.
+#' - `clean_outdated_http_interactions` (logical) Should outdated interactions
+#' be recorded back to file. Default: `FALSE`
 #'
 #'
 #' @examples
@@ -79,6 +91,7 @@
 #' vcr_configure(dir = tempdir(), ignore_hosts = "google.com")
 #' vcr_configure(dir = tempdir(), ignore_localhost = TRUE)
 #'
+#'
 #' # logging
 #' vcr_configure(dir = tempdir(), log = TRUE,
 #'   log_opts = list(file = file.path(tempdir(), "vcr.log")))