split qenv methods to separate pages and link in qenv() docs

Author: gogonzo

R/qenv-constructor.R

@@ -1,26 +1,18 @@
-#' Code tracking with `qenv` object
+#' Instantiates a `qenv` environment
 #'
 #' @description
 #' `r badge("stable")`
 #'
-#' Create a `qenv` object and evaluate code in it to track code history.
-#'
-#' @param names (`character`) for `x[names]`, names of objects included in `qenv` to subset. Names not present in `qenv`
-#' are skipped. For `get_code` `r lifecycle::badge("experimental")` vector of object names to return the code for.
-#' For more details see the "Extracting dataset-specific code" section.
+#' Instantiates a `qenv` environment.
 #'
 #' @details
+#' `qenv` class has following characteristics:
 #'
-#' `qenv()` instantiates a with an empty `qenv` environment.
-#'
-#' @section `qenv` characteristics:
-#'
-#' A `qenv` inherits from the `environment` class, behaves like an environment, and has the
-#' following characteristics:
-#'
-#' - `qenv` environment is locked, and data modification is only possible through the `eval_code()`
-#'   and `within()` functions.
-#' - It stores metadata about the code used to create the data.
+#' - It inherits from the environment and methods such as [`$`], [get()], [ls()], [as.list()],
+#' [parent.env()] work out of the box.
+#' - `qenv` is a locked environment, and data modification is only possible through the [eval_code()]
+#'   and [within.qenv()] functions.
+#' - It stores metadata about the code used to create the data (see [get_code()]).
 #' - Is immutable which means that each code evaluation does not modify the original `qenv`
 #'   environment directly. See the following code:
 #'
@@ -32,13 +24,14 @@
 #'
 #' @name qenv
 #'
-#' @return `qenv` returns a `qenv` object.
+#' @return `qenv` environment.
 #'
-#' @seealso [`base::within()`], [`get_var()`], [`get_env()`], [`get_warnings()`], [`join()`], [`concat()`]
+#' @seealso [eval_code()], [get_var()], [get_env()],[get_warnings()], [join()], [concat()]
 #' @examples
-#' # create empty qenv
-#' qenv()
-#'
+#' q <- qenv()
+#' q2 <- within(q, a <- 1)
+#' ls(q2)
+#' q2$a
 #' @export
 qenv <- function() {
   methods::new("qenv")

R/qenv-eval_code.R

@@ -4,18 +4,14 @@
 #'
 #' `eval_code()` evaluates given code in the `qenv` environment and appends it to the `code` slot.
 #' Thus, if the `qenv` had been instantiated empty, contents of the environment are always a result of the stored code.
-#' The `qenv` object is immutable, even though it inherits from the environment class, which is typically mutable by
-#' design. This means that each code evaluation does not modify the original `qenv` object directly. Instead, every
-#' code evaluation creates a new `qenv` object that reflects the result of the changes, leaving the original object
-#' unchanged.
 #'
 #' @param object (`qenv`)
 #' @param code (`character`, `language` or `expression`) code to evaluate.
 #' It is possible to preserve original formatting of the `code` by providing a `character` or an
 #' `expression` being a result of `parse(keep.source = TRUE)`.
 #'
 #' @return
-#' `eval_code` and `within` returns a `qenv` object with `expr` evaluated or `qenv.error` if evaluation fails.
+#' Returns a `qenv` object with `code/expr` evaluated or `qenv.error` if evaluation fails.
 #'
 #' @examples
 #' # evaluate code in qenv
@@ -25,8 +21,6 @@
 #' q <- eval_code(q, quote(library(checkmate)))
 #' q <- eval_code(q, expression(assert_number(a)))
 #'
-#' @name eval_code
-#' @rdname qenv
 #' @aliases eval_code,qenv,character-method
 #' @aliases eval_code,qenv,language-method
 #' @aliases eval_code,qenv,expression-method

R/qenv-extract.R

@@ -1,21 +1,19 @@
+#' Subset `qenv`
 #'
-#' @section Subsetting by the `names`:
-#'
-#' `x[names]` subsets `qenv` environment and limits the code to the necessary needed to build limited objects.
-#' `...` passes parameters to further methods.
+#' @description
+#' Subsets [`qenv`] environment and limits the code to the necessary needed to build limited objects.
 #'
 #' @param x (`qenv`)
+#' @param names (`character`) names of objects included in [`qenv`] to subset. Names not present in [`qenv`]
+#' are skipped.
+#' @param ... internal usage, please ignore.
 #'
 #' @examples
-#'
-#' # Subsetting
 #' q <- qenv()
 #' q <- eval_code(q, "a <- 1;b<-2")
 #' q["a"]
 #' q[c("a", "b")]
 #'
-#' @rdname qenv
-#'
 #' @export
 `[.qenv` <- function(x, names, ...) {
   checkmate::assert_character(names, any.missing = FALSE)

R/qenv-get_code.R

@@ -1,40 +1,17 @@
-#' @name qenv-inheritted
-#' @rdname qenv
-#'
-#' @details
-#'
-#' `x[[name]]`, `x$name` and `get(name, x)` are generic \R operators to access the objects in the environment.
-#' See [`[[`] for more details.
-#' `names(x)` calls on the `qenv` object and will list all objects in the environment.
-#'
-#' @return `[[`, `$` and `get` return the value of the object named `name` in the `qenv` object.
-#' @return `names` return a character vector of all the names of the objects in the `qenv` object.
-#' @return `ls` return a character vector of the names of the objects in the `qenv` object.
-#' It will only show the objects that are not named with a dot prefix, unless
-#' the `all.names = TRUE`, which will show all objects.
-#'
-#' @examples
-#' # Extract objects from qenv
-#' q[["a"]]
-#' q$a
-#'
-#' # list objects in qenv
-#' names(q)
-NULL
-
 #' Get code from `qenv`
 #'
-#' @details
-#' `get_code()` retrieves the code stored in the `qenv`. `...` passes arguments to methods.
+#' @description
+#' Retrieves the code stored in the `qenv`.
 #'
 #' @param object (`qenv`)
 #' @param deparse (`logical(1)`) flag specifying whether to return code as `character` or `expression`.
-#' @param ... see `Details`
-#'
+#' @param ... internal usage, please ignore.
+#' @param names (`character`) `r lifecycle::badge("experimental")` vector of object names to return the code for.
+#' For more details see the "Extracting dataset-specific code" section.
 #'
-#' @section Subsetting by the `names`:
+#' @section Extracting dataset-specific code:
 #'
-#' `get_code(x, names)` limits the returned code to contain only those lines needed to _create_
+#' `get_code(object, names)` limits the returned code to contain only those lines needed to _create_
 #' the requested objects. The code stored in the `qenv` is analyzed statically to determine
 #' which lines the objects of interest depend upon. The analysis works well when objects are created
 #' with standard infix assignment operators (see `?assignOps`) but it can fail in some situations.
@@ -99,7 +76,7 @@ NULL
 #' - creating and evaluating language objects, _e.g._ `eval(<call>)`
 #'
 #' @return
-#' `get_code` returns the traced code in the form specified by `deparse`.
+#' Returns the traced code in the form specified by `deparse`.
 #'
 #' @examples
 #' # retrieve code
@@ -115,8 +92,6 @@ NULL
 #' q <- eval_code(q, code = c("a <- 1", "b <- 2"))
 #' get_code(q, names = "a")
 #'
-#' @name get_code
-#' @rdname qenv
 #' @aliases get_code,qenv-method
 #' @aliases get_code,qenv.error-method
 #'

R/qenv-get_var.R

@@ -1,8 +1,9 @@
 #' Get object from `qenv`
 #'
 #' @description
-#' `r lifecycle::badge("deprecated")` by native \R operators/functions:
-#' `x[[name]]`, `x$name` or [get()].
+#' `r lifecycle::badge("deprecated")`
+#' Instead of [get_var()] use native \R operators/functions:
+#' `x[[name]]`, `x$name` or [get()]:
 #'
 #' Retrieve variables from the `qenv` environment.
 #'
@@ -17,8 +18,6 @@
 #' q2 <- eval_code(q1, code = "b <- a")
 #' get_var(q2, "b")
 #'
-#' @name get_var
-#' @rdname get_var
 #' @aliases get_var,qenv,character-method
 #' @aliases get_var,qenv.error,ANY-method
 #'

R/qenv-within.R

@@ -1,22 +1,17 @@
-#' Evaluate Expression in `qenv`
-#'
 #' @details
-#' `within()` is a convenience function for evaluating inline code inside the environment of a `qenv`.
-#' It is a method for the `base` generic that wraps `eval_code` to provide a simplified way of passing code.
-#' `within` accepts only inline expressions (both simple and compound) and allows for injecting values into `expr`
-#' through the `...` argument:
-#' as `name:value` pairs are passed to `...`, `name` in `expr` will be replaced with `value`.
+#' `within()` is a convenience method that wraps `eval_code` to provide a simplified way of passing expression.
+#' `within` accepts only inline expressions (both simple and compound) and allows to substitute `expr`
+#' with the `...` argument values.
 #'
 #' @section Using language objects with `within`:
 #' Passing language objects to `expr` is generally not intended but can be achieved with `do.call`.
 #' Only single `expression`s will work and substitution is not available. See examples.
 #'
 #' @param data (`qenv`)
 #' @param expr (`expression`) to evaluate. Must be inline code, see `Using language objects...`
-#' @param ... see `Details`
+#' @param ... (`named`) argument value will substitute a symbol in the `expr` matched by the name.
+#' For practical examples see the #usage.
 #'
-#' @return
-#' `within` returns a `qenv` object with `expr` evaluated or `qenv.error` if evaluation fails.
 #'
 #' @examples
 #' # evaluate code using within
@@ -49,7 +44,7 @@
 #' within(q, exprlist) # fails
 #' do.call(within, list(q, do.call(c, exprlist)))
 #'
-#' @rdname qenv
+#' @rdname eval_code
 #'
 #' @export
 #'