merge subseting sections of [ and get_code

Author: gogonzo

R/qenv-constructor.R

@@ -18,11 +18,16 @@
 #' A `qenv` inherits from the `environment` class, behaves like an environment, and has the
 #' following characteristics:
 #'
-#' -	The environment is locked, and data modification is only possible through the `eval_code()`
+#' - `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.
-#' - Is immutable which means that each code evaluation does not modify the original `qenv` object
-#' directly.
+#' - Is immutable which means that each code evaluation does not modify the original `qenv`
+#' environment directly. See the following code:
+#'   ```
+#'   q1 <- qenv()
+#'   q2 <- eval_code(q1, "a <- 1")
+#'   identical(q1, q2) # FALSE
+#'   ```
 #'
 #' @name qenv
 #'

R/qenv-eval_code.R

@@ -1,6 +1,7 @@
 #' Evaluate code in `qenv`
 #'
 #' @details
+#'
 #' `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
@@ -14,7 +15,7 @@
 #' `expression` being a result of `parse(keep.source = TRUE)`.
 #'
 #' @return
-#' `eval_code` returns a `qenv` object with `expr` evaluated or `qenv.error` if evaluation fails.
+#' `eval_code` and `within` returns a `qenv` object with `expr` evaluated or `qenv.error` if evaluation fails.
 #'
 #' @examples
 #' # evaluate code in qenv

R/qenv-extract.R

@@ -1,6 +1,7 @@
 #'
-#' @section Subsetting:
-#' `x[names]` subsets objects in `qenv` environment and limit the code to the necessary needed to build limited objects.
+#' @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.
 #'
 #' @param x (`qenv`)

R/qenv-get_code.R

@@ -32,8 +32,9 @@ NULL
 #' @param ... see `Details`
 #'
 #'
-#' @section Extracting dataset-specific code:
-#' When `names` for `get_code` is specified, the code returned will be limited to the lines needed to _create_
+#' @section Subsetting by the `names`:
+#'
+#' `get_code(x, 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.