docs: improve documentation of prudence argument (#593)

* docs: improve documentation of `prudence` argument

* Revert bullets

* Clarify bullets

* Document

---------

Co-authored-by: Maëlle Salmon <maelle.salmon@yahoo.se>

Author: krlmlr

R/compute-rd.R

@@ -12,13 +12,15 @@
 #' @param name The name of the table to store the result in.
 #' @param schema_name The schema to store the result in, defaults to the current schema.
 #' @param temporary Set to `FALSE` to store the result in a permanent table.
-#' @param prudence Convenience argument to control automatic materialization of data.
+#' @param prudence Memory protection, controls if DuckDB may convert
+#'   intermediate results in DuckDB-managed memory to data frames in R memory.
 #'
 #'   - `"lavish"`: regardless of size,
 #'   - `"frugal"`: never,
 #'   - `"thrifty"`: up to a maximum size of 1 million cells.
 #'
 #' The default is to inherit from the input.
+#' This argument is provided here only for convenience.
 #' The same effect can be achieved by forwarding the output to [as_duckdb_tibble()]
 #' with the desired prudence.
 #' See `vignette("prudence")` for more information.

R/ducktbl.R

@@ -11,7 +11,8 @@
 #'
 #' @param ... For `duckdb_tibble()`, passed on to [tibble()].
 #'   For `as_duckdb_tibble()`, passed on to methods.
-#' @param prudence,.prudence Controls automatic materialization of data.
+#' @param prudence,.prudence Memory protection, controls if DuckDB may convert
+#'   intermediate results in DuckDB-managed memory to data frames in R memory.
 #'
 #'   - `"lavish"`: regardless of size,
 #'   - `"frugal"`: never,

R/io2.R

@@ -90,7 +90,8 @@ read_json_duckdb <- function(path, ..., prudence = c("thrifty", "lavish", "fruga
 #' @param table_function The name of a table-valued
 #'   DuckDB function such as `"read_parquet"`,
 #'   `"read_csv"`, `"read_csv_auto"` or `"read_json"`.
-#' @param prudence Controls automatic materialization of data.
+#' @param prudence Memory protection, controls if DuckDB may convert
+#'   intermediate results in DuckDB-managed memory to data frames in R memory.
 #'
 #'   - `"thrifty"`: up to a maximum size of 1 million cells,
 #'   - `"lavish"`: regardless of size,