Expand documentation for the use and reproducibility of side effects functions in qenv

R/qenv-within.R

@@ -3,7 +3,8 @@
 #' `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 `...` named argument values.
-#'
+#' Functions that trigger side effects like `options` or `set.seed` can be linked to specific objects for further code retrieval (with `get_code`), but only through `eval_code` where code input as `character`. `within` works on `expressions` that do not preserve comments, hence you can not use `# @linksto` tag explained in `get_code`.
+#' @alias within
 #' @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.

vignettes/qenv.Rmd

@@ -185,6 +185,34 @@ if (interactive()) {
 }
 ```
 
+### Reproducibility
+
+The code inside a `qenv` object can be retrieved using `get_code` function.
+```{r, get_code}
+q_reproducible <- qenv()
+q_reproducible <- within(q_reproducible, {
+  a <- 2
+  b <- 5
+  c <- a + b
+})
+cat(get_code(q_reproducible))
+cat(get_code(q_reproducible, names = "a"))
+cat(get_code(q_reproducible, names = "c"))
+```
+
+As demonstrated, you can retrieve the code responsible for creating specific objects by passing the object's name to the `names` argument in `get_code`.
+In scenarios where certain objects are **affected by side effects** (such as setting options or controlling random number generation) from previous calls, this dependency can be specified in the `qenv`. You achieve this by adding the comment `# @linksto` followed by the name of the linked object.
+
+```{r, get_code_linked}
+q_linked <- qenv()
+q_linked <- eval_code(q_reproducible, "
+  set.seed(2) # @linksto a
+  a <- runif(1)
+")
+cat(get_code(q_linked))
+cat(get_code(q_linked, names = "a"))
+```
+Currently, object linking for reproducibility is only supported by the `eval_code` function. Since `within` uses an expression as input and ignores comments, its use is **not recommended** when side-effect functions are required for full reproducibility.
 
 ## `qenv` and `teal` applications