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

R/qenv-within.R

@@ -3,6 +3,10 @@
 #' `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` cannot be linked to specific objects with
+#' tag "`# @linksto <object name>`" as expressions ignore comments. This is relevant when we want
+#' to reproduce the code with
+#' function `get_code`. For such scenarios, we recommend to use `eval_code` instead.
 #'
 #' @section Using language objects with `within`:
 #' Passing language objects to `expr` is generally not intended but can be achieved with `do.call`.

vignettes/qenv.Rmd

@@ -185,6 +185,38 @@ if (interactive()) {
 }
 ```
 
+### Reproducibility
+
+Code inside a `qenv` can be reproduced by calling function `get_code`
+```{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 shown, we can get the code for specific objects by referencing the name of the object with the `names` argument
+in `get_code`.
+In the scenarios where we have specific objects that are affected by side effects of previous calls, it can be
+passed to the qenv by adding # @linksto + the name of the object that is linked. This is important for setting options
+or controlling random number generation.
+
+```{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"))
+```
+Linking of objects for reproducibility is currently only supported by `eval_code`. As `within` uses expression as input
+and ignores comments, it is not recommended in the cases where side effects functions are required for reproducibility.
 
 ## `qenv` and `teal` applications