docs: #271 #213 clarify get_datasets and add keep_source_vars to prog…

… strat

R/datasets.R

@@ -1,5 +1,21 @@
 #' Retrieve a Dataset from the `admiraldev_environment` environment
 #'
+#' @details
+#' Once in a while, we may encounter "locked binding for 'xxx'." errors
+#' during the development process while building out functions. This may arise because
+#' we want to create dynamic data/objects based on user-inputs that need modification
+#' at points in time after the package has been loaded. To manage such data or objects,
+#' R has a data structure known as an 'environment'. These environment objects are created
+#' at build time, but can be populated with values after the package has been loaded and
+#' update those values over the course of an R session.
+#'
+#' Currently we only support two datasets inside our `admiraldev_environment` object:
+#'  - `one_to_many`
+#'  - `many_to_one`
+#'
+#' The purpose of `get_dataset` is to retrieve the datasets contained
+#' inside `admiraldev_environment`.
+#'
 #' @param name The name of the dataset to retrieve
 #'
 #' @return A `data.frame`

vignettes/programming_strategy.Rmd

@@ -221,6 +221,9 @@ Arguments which expect a boolean or boolean vector must start with a verb, e.g.,
 | `date`           | Date of an event / interval. Expects a date object.                                                                |
 | `set_values_to`  | List of variable name-value pairs. Use `process_set_values_to()` for processing the value and providing user friendly error messages. |
 | `subject_keys`   | Variables to uniquely identify a subject, defaults to `exprs(STUDYID, USUBJID)`. In function formals, use `subject_keys = get_admiral_option("subject_keys")`                                     |
+| `keep_source_vars` | Specifies which variables from the selected observations should be kept                                          |
+
+The default of the parameter should be everything().
 
 
 ## Source Code Formatting