docs: implements @gogonzo suggestions and cleans up docs

Author: averissimo

DESCRIPTION

@@ -66,6 +66,7 @@ Collate:
     'qenv-length.R'
     'qenv-show.R'
     'qenv-within.R'
+    'qenv-z-environment.R'
     'teal.code-package.R'
     'utils-get_code_dependency.R'
     'utils.R'

R/qenv-constructor.R

@@ -14,6 +14,19 @@
 #' `new_qenv()` (`r badge("deprecated")` and not recommended)
 #' can instantiate a `qenv` object with data in the environment and code registered.
 #'
+#' @section Extracting objects from `qenv`:
+#'
+#' Extracting an object from the `qenv` by name can be done using the following methods:
+#'
+#' - `x[[name]]`
+#' - `x$name`
+#' - `get(name, envir = x)`
+#'
+#' note: `get_var(name)` was superseded by the native \R methods above.
+#'
+#' To list all objects in the environment, use `ls(x)` (which doesn't show
+#' objects that have a dot prefix with default arguments) or `names(x)` (shows all objects).
+#'
 #' @section Environment:
 #'
 #' The `qenv` object behaves like an environment that is locked and one can use
@@ -38,7 +51,6 @@ qenv <- function() {
   methods::new("qenv")
 }
 
-
 #' @param code `r badge("deprecated")`
 #'  (`character(1)` or `language`) code to evaluate. Accepts and stores comments also.
 #' @param env `r badge("deprecated")` (`environment`)

R/qenv-eval_code.R

@@ -1,7 +1,7 @@
 #' Evaluate code in `qenv`
 #'
 #' @details
-#' `eval_code` evaluates given code in the `qenv` environment and appends it to the `code` slot.
+#' `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.
 #'
 #' @param object (`qenv`)

R/qenv-get_code.R

@@ -1,7 +1,7 @@
 #' Get code from `qenv`
 #'
 #' @details
-#' `get_code` retrieves the code stored in the `qenv`. `...` passes arguments to methods.
+#' `get_code()` retrieves the code stored in the `qenv`. `...` passes arguments to methods.
 #'
 #' @param object (`qenv`)
 #' @param deparse (`logical(1)`) flag specifying whether to return code as `character` or `expression`.

R/qenv-get_var.R

@@ -1,5 +1,9 @@
 #' Get object from `qenv`
 #'
+#' @description
+#' `r lifecycle::badge("superseded")` by native \R operators/functions:
+#' `x[[name]]`, `x$name` or `get(name, envir = qenv)`.
+#'
 #' Retrieve variables from the `qenv` environment.
 #'
 #' @param object,x (`qenv`)
@@ -12,7 +16,6 @@
 #' q1 <- eval_code(q, code = quote(a <- 1))
 #' q2 <- eval_code(q1, code = "b <- a")
 #' get_var(q2, "b")
-#' q2[["b"]]
 #'
 #' @name get_var
 #' @rdname get_var
@@ -43,7 +46,6 @@ setMethod("get_var", signature = c("qenv.error", "ANY"), function(object, var) {
   ))
 })
 
-#' @rdname get_var
 setMethod("[[", signature = c("qenv", "ANY"), function(x, i) {
   get_var(x, i)
 })

R/qenv-within.R

@@ -1,7 +1,7 @@
 #' Evaluate Expression in `qenv`
 #'
 #' @details
-#' `within` is a convenience function for evaluating inline code inside the environment of a `qenv`.
+#' `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:

R/qenv-z-environment.R

@@ -0,0 +1,24 @@
+#' @name qenv-inheritted
+#' @rdname qenv
+#'
+#' @param x (`qenv`) object.
+#' @param name (`character`) name of object.
+#' @param pos,envir,all.names,pattern,sorted see [ls()] function for details.
+#'
+#' @usage x[[name]]
+#' x$name
+#' names(x)
+#' ls(name, pos = -1L, envir = as.environment(pos),
+#'    all.names = FALSE, pattern, sorted = TRUE)
+#'
+#' @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)` and `ls(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.
+NULL