datanames in vignettes (#357)

see insightsengineering/teal.code#239

Refers to #338

Modified a documentation a little bit to emphasize inheritance from
environment.

Author: gogonzo

R/teal_data-constructor.R

@@ -3,7 +3,7 @@
 #' @description
 #' `r lifecycle::badge("stable")`
 #'
-#' Universal function to pass data to teal application.
+#' Initializes a data for `teal` application.
 #'
 #' @param ... any number of objects (presumably data objects) provided as `name = value` pairs.
 #'
@@ -14,10 +14,28 @@
 #' @param code (`character`, `language`) optional code to reproduce the datasets provided in `...`.
 #'  Note this code is not executed and the `teal_data` may not be reproducible
 #'
-#'  Use [verify()] to verify code reproducibility .
+#'  Use [verify()] to verify code reproducibility.
+#'
+#' @details
+#'
+#' A `teal_data` is meant to be used for reproducibility purposes. The class inherits from
+#' [`teal.data::qenv`] and we encourage to get familiar with \CRANpkg{teal.code} first.
+#' `teal_data` has following characteristics:
+#'
+#' - It inherits from the environment and methods such as [`$`], [get()], [ls()], [as.list()],
+#' [parent.env()] work out of the box.
+#' - `teal_data` is a locked environment, and data modification is only possible through the
+#' [teal.code::eval_code()] and [within.qenv()] functions.
+#' - It stores metadata about the code used to create the data (see [get_code()]).
+#' - It supports slicing (see [`teal.code::subset-qenv`])
+#' - Is immutable which means that each code evaluation does not modify the original `teal_data`
+#'   environment directly.
+#' - It maintains information about relationships between datasets (see [join_keys()]).
 #'
 #' @return A `teal_data` object.
 #'
+#' @seealso [`teal.code::eval_code`], [get_code()], [join_keys()], [names.teal_data()]
+#'
 #' @export
 #'
 #' @examples

R/teal_data-show.R

@@ -16,5 +16,6 @@ setMethod("show", signature = "teal_data", function(object) {
   } else {
     cat("\u2716", "unverified teal_data object\n")
   }
-  rlang::env_print(teal.code::get_env(object))
+  methods::callNextMethod(object)
+  invisible(object)
 })

man/cdisc_data.Rd

@@ -11,12 +11,21 @@ vignette: >
 # Introduction
 
 The `teal.data` package specifies the data format used in `teal` applications. 
-The `teal_data` class inherits from [`qenv`](https://insightsengineering.github.io/teal.code/latest-tag/articles/qenv.html) and is meant to be used for reproducibility purposes. 
+
+
+A `teal_data` is meant to be used for reproducibility purposes. The class inherits from [`qenv`](https://insightsengineering.github.io/teal.code/latest-tag/articles/qenv.html) and we encourage to get familiar with [`teal.code`](https://insightsengineering.github.io/teal.code/latest-tag/) first. `teal_data` has following characteristics:
+
+- It inherits from the environment and methods such as `$`, `get()`, `ls()`, `as.list()` work out of the box.
+- `teal_data` is a locked environment, and data modification is only possible through the `teal.code::eval_code()` and `within.qenv()` functions.
+- It stores metadata about the code used to create the data (see [reproducibility](#reproducibility)).
+- It supports slicing by `[`.
+- It is immutable which means that each code evaluation does not modify the original `teal_data` environment directly.
+- It maintains information about relationships between datasets (see [Join Keys](#relational-data-models)).
 
 ## Quick Start
 
 To create an object of class `teal_data`, use the `teal_data` function.
-`teal_data` has a number of methods to manage relevant information in private class slots.
+`teal_data` has a number of methods to interact with the object.
 
 ```{r, results = 'hide', message = FALSE}
 library(teal.data)
@@ -46,23 +55,14 @@ get_code(my_data)
 
 # get code just for specific object
 get_code(my_data, names = "data2")
+
 # get datanames
 names(my_data)
 
 # print
 print(my_data)
 ```
 
-
-## `teal_data` characteristics
-
-A `teal_data` object keeps the following information:
-
-- `env` - an environment containing data.
-- `code` - a string containing code to reproduce `env` (details in [reproducibility](teal-data-reproducibility.html)).
-- `names` - a character vector listing objects of interest to `teal` modules (details in [this `teal` vignette](https://insightsengineering.github.io/teal/latest-tag/articles/including-data-in-teal-applications.html)).
-- `join_keys` - a `join_keys` object defining relationships between datasets (details in [Join Keys](join-keys.html)).
-
 ### Reproducibility
 
 The primary function of `teal_data` is to provide reproducibility of data.
@@ -104,8 +104,8 @@ join_keys(my_data["child"])
 
 ### Hidden objects
 
-An object is hidden in `teal_data` if its name starts with a dot (`.`).
-This can be used to pass auxiliary objects / function in the `teal_data` instance, without being visible in the `teal` summary and filter panel.
+An object is hidden in `teal_data` if its name starts with a dot (`.`). This can be used to pass auxiliary objects in
+the `teal_data` instance, without being visible in the `teal` summary and filter panel.
 
 ```{r}
 my_data <- teal_data()
@@ -114,5 +114,6 @@ my_data <- within(my_data, {
   .data2 <- data.frame(id = 1:20, data_id = c(1:10, 1:10), y = 21:30)
 })
 
+ls(my_data)
 names(my_data)
 ```