doc: adds section to qenv constructor

Author: averissimo

R/qenv-constructor.R

@@ -10,9 +10,31 @@
 #' `qenv()` instantiates a `qenv` with an empty environment.
 #' Any changes must be made by evaluating code in it with `eval_code` or `within`, thereby ensuring reproducibility.
 #'
+#'
 #' `new_qenv()` (`r badge("deprecated")` and not recommended)
 #' can instantiate a `qenv` object with data in the environment and code registered.
 #'
+#' @section Environment:
+#'
+#' The `qenv` object behaves as an environment that is locked and can be used as
+#' as a argument to with many functions that accept `environment`, among the
+#' most relevant are: `names()`, `ls()`, `get()`, `exists()`, `parent.env()`,
+#' `{l,s,v}apply` family, `local`, `as.environment()`, `is.environment()`, `as.list()`, ...
+#'
+#' `qenv` should not be used with `cbind()` and `env.profile()` functions as it
+#' has unexpected behavior.
+#' Instead, `get_env()` or `as.environment()` should be used before calling any
+#' problematic function.
+#'
+#' Similarly, `rlang` functions related to environments cannot be used directly
+#' with `qenv` and should be used with `teal.code::get_env()`/`as.environment()`.
+#'
+#' ```r
+#' q <- qenv()
+#' rlang::env_clone(as.environment(q))
+#' rlang::env_clone(get_env(q))
+#' ```
+#'
 #' @name qenv
 #'
 #' @return `qenv` and `new_qenv` return a `qenv` object.