335 bring teal_slice(s) to package index and create separate man pa…

…ges for `teal_slice(s)` utilities (#572) Closes #335 - Created separate documentation page for `teal_slice-utilities` - included `is.teal_slice`, `as.teal_slice`, `as.list.teal_slice`, `print.teal_slice`, `format.teal_slice` - inheriting params from `teal_slice` - inheriting examples from `teal_slice` - man page contains `@keywords internal` so does not appear in package index - `teal_slice` man page - extended `@seealso` section to point to utility functions - utility functions mentioned in the `@description` of the page - utilities visible in examples Did the same for `teal_slices` and respective utility functions. Utility functions are not visible in package index, where `teal_slice` and `teal_slices` were brought back to package index <img width="514" alt="image" src="https://github.com/insightsengineering/teal.slice/assets/133694481/748cb0ba-6e5d-414b-9ae8-ef3b77348e22"> --------- Co-authored-by: Dony Unardi <[email protected]>
insightsengineering · Mar 21, 2024 · 0bdd187 · 0bdd187
1 parent 3f1c06d
commit 0bdd187
Show file tree

Hide file tree

Showing 7 changed files with 211 additions and 97 deletions.
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,9 @@
 # teal.slice 0.5.0.9008
 
+### Miscellaneous
+
+* Added `teal_slice` and `teal_slices` to package index. 
+
 # teal.slice 0.5.0
 
 ### Enhancements

diff --git a/R/teal_slice.R b/R/teal_slice.R
@@ -1,6 +1,7 @@
 #' Specify single filter
 #'
 #' Create a `teal_slice` object that holds complete information on filtering one variable.
+#' Check out [`teal_slice-utilities`] functions for working with `teal_slice` object.
 #'
 #' `teal_slice` object fully describes filter state and can be used to create,
 #' modify, and delete a filter state. A `teal_slice` contains a number of common fields
@@ -67,12 +68,7 @@
 #' @param fixed (`logical(1)`) flag specifying whether to fix this filter state (forbid setting state)
 #' @param anchored (`logical(1)`) flag specifying whether to lock this filter state (forbid removing and inactivating)
 #' @param title (`character(1)`) optional title of the filter. Ignored when `varname` is set.
-#' @param ... in `teal_slice` method these are additional arguments which can be handled by extensions
-#'  of `teal.slice` classes. In other methods these are further arguments passed to or from other methods.
-#' @param x (`teal.slice`)
-#' @param show_all (`logical(1)`) indicating whether to show all fields. If set to `FALSE`,
-#'  only non-NULL elements will be printed.
-#' @param trim_lines (`logical(1)`) indicating whether to trim lines when printing.
+#' @param ... additional arguments which can be handled by extensions of `teal.slice` classes.
 #'
 #' @return A `teal.slice` object. Depending on whether `varname` or `expr` was specified, the resulting
 #' `teal_slice` also receives class `teal_slice_var` or `teal_slice_expr`, respectively.
@@ -108,7 +104,8 @@
 #' print(x1)
 #' print(x1, show_all = TRUE, trim_lines = FALSE)
 #'
-#' @seealso [`teal_slices`]
+#' @seealso [`teal_slices`],
+#' [`is.teal_slice`], [`as.teal_slice`], [`as.list.teal_slice`], [`print.teal_slice`], [`format.teal_slice`]
 #'
 #' @export
 teal_slice <- function(dataname,
@@ -172,26 +169,35 @@ teal_slice <- function(dataname,
   ans
 }
 
-#' @rdname teal_slice
-#' @export
+#' `teal_slice` utility functions
+#'
+#' Helper functions for working with [`teal_slice`] object.
+#' @param x (`teal.slice`)
+#' @param show_all (`logical(1)`) indicating whether to show all fields. If set to `FALSE`,
+#'  only non-NULL elements will be printed.
+#' @param trim_lines (`logical(1)`) indicating whether to trim lines when printing.
+#' @param ... additional arguments passed to other functions.
+#' @name teal_slice-utilities
+#' @inherit teal_slice examples
 #' @keywords internal
+
+#' @rdname teal_slice-utilities
+#' @export
 #'
 is.teal_slice <- function(x) { # nolint
   inherits(x, "teal_slice")
 }
 
-#' @rdname teal_slice
+#' @rdname teal_slice-utilities
 #' @export
-#' @keywords internal
 #'
 as.teal_slice <- function(x) { # nolint
   checkmate::assert_list(x, names = "named")
   do.call(teal_slice, x)
 }
 
-#' @rdname teal_slice
+#' @rdname teal_slice-utilities
 #' @export
-#' @keywords internal
 #'
 as.list.teal_slice <- function(x, ...) {
   formal_args <- setdiff(names(formals(teal_slice)), "...")
@@ -209,9 +215,8 @@ as.list.teal_slice <- function(x, ...) {
 }
 
 
-#' @rdname teal_slice
+#' @rdname teal_slice-utilities
 #' @export
-#' @keywords internal
 #'
 format.teal_slice <- function(x, show_all = FALSE, trim_lines = TRUE, ...) {
   checkmate::assert_flag(show_all)
@@ -223,9 +228,8 @@ format.teal_slice <- function(x, show_all = FALSE, trim_lines = TRUE, ...) {
   jsonify(x_list, trim_lines)
 }
 
-#' @rdname teal_slice
+#' @rdname teal_slice-utilities
 #' @export
-#' @keywords internal
 #'
 print.teal_slice <- function(x, ...) {
   cat(format(x, ...))

diff --git a/R/teal_slices.R b/R/teal_slices.R
@@ -1,6 +1,7 @@
 #' Complete filter specification
 #'
 #' Create `teal_slices` object to package multiple filters and additional settings.
+#' Check out [`teal_slices-utilities`] functions for working with `teal_slices` object.
 #'
 #' `teal_slices()` collates multiple `teal_slice` objects into a `teal_slices` object,
 #' a complete filter specification. This is used by all classes above `FilterState`
@@ -12,8 +13,7 @@
 #' Since these could be mutually exclusive, it is impossible to set both allowed and forbidden
 #' variables for one data set in one `teal_slices`.
 #'
-#' @param ... any number of `teal_slice` objects. For `print` and `format`,
-#'  additional arguments passed to other functions.
+#' @param ... any number of `teal_slice` objects.
 #' @param include_varnames,exclude_varnames (`named list`s of `character`) where list names
 #'  match names of data sets and vector elements match variable names in respective data sets;
 #'  specify which variables are allowed to be filtered; see `Details`.
@@ -28,9 +28,6 @@
 #'   and unfiltered dataset. Note, that issues were reported when using this option with `MultiAssayExperiment`.
 #'   Please make sure that adding new filters doesn't fail on target platform before deploying for production.
 #' @param allow_add (`logical(1)`) logical flag specifying whether the user will be able to add new filters
-#' @param x object to test for `teal_slices`, object to convert to `teal_slices` or a `teal_slices` object
-#' @param i (`character` or `numeric` or `logical`) indicating which elements to extract
-#' @param recursive (`logical(1)`) flag specifying whether to also convert to list the elements of this `teal_slices`
 #'
 #' @return
 #' `teal_slices`, which is an unnamed list of `teal_slice` objects.
@@ -85,6 +82,8 @@
 #' @seealso
 #' - [`teal_slice`] for creating constituent elements of `teal_slices`
 #' - [`teal::slices_store`] for robust utilities for saving and loading `teal_slices` in `JSON` format
+#' - [`is.teal_slices`], [`as.teal_slices`], [`as.list.teal_slices`], [`[.teal_slices`], [`c.teal_slices`]
+#' [`print.teal_slices`], [`format.teal_slices`]
 #'
 #' @export
 #'
@@ -126,19 +125,26 @@ teal_slices <- function(...,
   )
 }
 
+#' `teal_slices` utility functions
+#'
+#' Helper functions for working with [`teal_slices`] object.
+#' @param x object to test for `teal_slices`, object to convert to `teal_slices` or a `teal_slices` object
+#' @param i (`character` or `numeric` or `logical`) indicating which elements to extract
+#' @param recursive (`logical(1)`) flag specifying whether to also convert to list the elements of this `teal_slices`
+#' @param ... additional arguments passed to other functions.
+#' @name teal_slices-utilities
+#' @inherit teal_slices examples
+#' @keywords internal
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 is.teal_slices <- function(x) { # nolint
   inherits(x, "teal_slices")
 }
 
-
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 as.teal_slices <- function(x) { # nolint
   checkmate::assert_list(x)
@@ -150,9 +156,8 @@ as.teal_slices <- function(x) { # nolint
 }
 
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint
   ans <- unclass(x)
@@ -161,9 +166,8 @@ as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint
 }
 
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 `[.teal_slices` <- function(x, i) {
   if (missing(i)) i <- seq_along(x)
@@ -185,9 +189,8 @@ as.list.teal_slices <- function(x, recursive = FALSE, ...) { # nolint
 }
 
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 c.teal_slices <- function(...) {
   x <- list(...)
@@ -207,11 +210,10 @@ c.teal_slices <- function(...) {
 }
 
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @param show_all (`logical(1)`) whether to display non-null elements of constituent `teal_slice` objects
 #' @param trim_lines (`logical(1)`) whether to trim lines
 #' @export
-#' @keywords internal
 #'
 format.teal_slices <- function(x, show_all = FALSE, trim_lines = TRUE, ...) {
   checkmate::assert_flag(show_all)
@@ -228,9 +230,8 @@ format.teal_slices <- function(x, show_all = FALSE, trim_lines = TRUE, ...) {
   jsonify(slices_list, trim_lines)
 }
 
-#' @rdname teal_slices
+#' @rdname teal_slices-utilities
 #' @export
-#' @keywords internal
 #'
 print.teal_slices <- function(x, ...) {
   cat(format(x, ...), "\n")

diff --git a/man/teal_slice-utilities.Rd b/man/teal_slice-utilities.Rd
diff --git a/man/teal_slice.Rd b/man/teal_slice.Rd