Add Value documentation for all functions (#896)

Closes #871 

---------

Co-authored-by: Davide Garolini <davide.garolini@roche.com>

NAMESPACE

@@ -9,11 +9,8 @@ S3method(a_summary,factor)
 S3method(a_summary,logical)
 S3method(a_summary,numeric)
 S3method(as.rtable,data.frame)
-S3method(drawDetails,dynamicSplitText)
 S3method(h_coxreg_inter_effect,factor)
 S3method(h_coxreg_inter_effect,numeric)
-S3method(heightDetails,decoratedGrob)
-S3method(heightDetails,dynamicSplitText)
 S3method(s_compare,character)
 S3method(s_compare,factor)
 S3method(s_compare,logical)
@@ -30,10 +27,6 @@ S3method(tidy,coxreg.univar)
 S3method(tidy,glm)
 S3method(tidy,step)
 S3method(tidy,summary.coxph)
-S3method(validDetails,decoratedGrob)
-S3method(validDetails,dynamicSplitText)
-S3method(widthDetails,decoratedGrob)
-S3method(widthDetails,dynamicSplitText)
 export(CombinationFunction)
 export(a_compare)
 export(a_count_occurrences)

R/abnormal.R

@@ -6,20 +6,20 @@
 #' and additional analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or
 #' `factor`). For each direction specified in `abnormal` (e.g. high or low) count patients in the
 #' numerator and denominator as follows:
-#' \describe{
-#'   \item{num}{the number of patients with this abnormality recorded while on treatment.}
-#'   \item{denom}{the number of patients with at least one post-baseline assessment.}
-#' }
-#' Note, the denominator includes patients that might have other abnormal levels at baseline,
-#' and patients with missing baseline. Note, optionally patients with this abnormality at
-#' baseline can be excluded from numerator and denominator.
-#'
-#' @details Note that `df` should be filtered to include only post-baseline records.
+#'   * `num` : The number of patients with this abnormality recorded while on treatment.
+#'   * `denom`: The number of patients with at least one post-baseline assessment.
 #'
 #' @inheritParams argument_convention
-#' @param abnormal (`named list`)\cr identifying the abnormal range level(s) in `var`. Default to
-#' `list(Low = "LOW", High = "HIGH")` but you can also group different levels into the name list,
-#' for example, `abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))`
+#' @param abnormal (named `list`)\cr list identifying the abnormal range level(s) in `var`. Defaults to
+#'   `list(Low = "LOW", High = "HIGH")` but you can also group different levels into the named list,
+#'   for example, `abnormal = list(Low = c("LOW", "LOW LOW"), High = c("HIGH", "HIGH HIGH"))`.
+#'
+#' @note
+#' * `count_abnormal()` only works with a single variable containing multiple abnormal levels.
+#' * `df` should be filtered to include only post-baseline records.
+#' * the denominator includes patients that might have other abnormal levels at baseline,
+#'   and patients with missing baseline. Patients with these abnormalities at
+#'   baseline can be optionally excluded from numerator and denominator.
 #'
 #' @name abnormal
 #' @include formats.R
@@ -29,8 +29,9 @@ NULL
 #'   for a single `abnormal` level.
 #' @param exclude_base_abn (`flag`)\cr whether to exclude subjects with baseline abnormality
 #'   from numerator and denominator.
-#' @return [s_count_abnormal()] returns the statistic `fraction` which is a
-#'   vector with `num` and `denom` counts of patients.
+#'
+#' @return
+#' * `s_count_abnormal()` returns the statistic `fraction` which is a vector with `num` and `denom` counts of patients.
 #'
 #' @examples
 #' library(dplyr)
@@ -105,10 +106,10 @@ s_count_abnormal <- function(df,
   result
 }
 
-#' @describeIn abnormal Formatted Analysis function which can be further customized by calling
-#'   [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()].
+#' @describeIn abnormal Formatted analysis function which is used as `afun` in `count_abnormal()`.
 #'
-#' @return [a_count_abnormal()] returns the corresponding list with formatted [rtables::CellValue()].
+#' @return
+#' * `a_count_abnormal()` returns the corresponding list with formatted [rtables::CellValue()].
 #'
 #' @examples
 #' # Internal function - a_count_abnormal
@@ -124,10 +125,14 @@ a_count_abnormal <- make_afun(
   .formats = c(fraction = format_fraction)
 )
 
-#' @describeIn abnormal Layout creating function which can be used for creating tables, which can take
-#'   statistics function arguments and additional format arguments (see below). Note that it only
-#'   works with a single variable but multiple abnormal levels.
-#' @return [count_abnormal()] can be used with multiple abnormal levels and modifies the layout.
+#' @describeIn abnormal Layout-creating function which can take statistics function arguments
+#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
+#'
+#' @return
+#' * `count_abnormal()` returns a layout object suitable for passing to further layouting functions,
+#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing
+#'   the statistics from `s_count_abnormal()` to the table layout.
+#'
 #' @export
 #' @examples
 #' # Layout creating function.

R/abnormal_by_baseline.R

@@ -2,11 +2,8 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' @details
-#' Note that `df` should be filtered to include only post-baseline records.
-#'
-#' Primary analysis variable `.var` indicates the abnormal range result (character or factor), and additional
-#' analysis variables are `id` (character or factor) and `baseline` (character or factor). For each
+#' Primary analysis variable `.var` indicates the abnormal range result (`character` or `factor`), and additional
+#' analysis variables are `id` (`character` or `factor`) and `baseline` (`character` or `factor`). For each
 #' direction specified in `abnormal` (e.g. high or low) we condition on baseline range result and count
 #' patients in the numerator and denominator as follows:
 #'   * `Not <Abnormal>`
@@ -21,10 +18,15 @@
 #'
 #' @inheritParams argument_convention
 #' @param abnormal (`character`)\cr identifying the abnormal range level(s) in `.var`.
+#'
+#' @note
+#' * `df` should be filtered to include only post-baseline records.
+#' * If the baseline variable or analysis variable contains `NA`, it is expected that `NA` has been
+#'   conveyed to `na_level` appropriately beforehand with [df_explicit_na()] or [explicit_na()].
+#'
 #' @seealso Relevant description function [d_count_abnormal_by_baseline()].
 #'
 #' @name abnormal_by_baseline
-#' @include formats.R
 NULL
 
 #' Description Function for [s_count_abnormal_by_baseline()]
@@ -34,6 +36,7 @@ NULL
 #' Description function that produces the labels for [s_count_abnormal_by_baseline()].
 #'
 #' @inheritParams abnormal_by_baseline
+#' @return Abnormal category labels for [s_count_abnormal_by_baseline()].
 #'
 #' @examples
 #' d_count_abnormal_by_baseline("LOW")
@@ -52,14 +55,14 @@ d_count_abnormal_by_baseline <- function(abnormal) {
   )
 }
 
-#' @describeIn abnormal_by_baseline For a single `abnormal` level, produce a statistic `fraction` which is
-#'   a named list with 3 elements: `not_abnormal`, `abnormal` and `total`.
-#'   Each element contains a vector with `num` and `denom` counts of patients.
-#'   Please note that if the baseline variable or analysis variable contains `NA`, it is expected that `NA` has been
-#'   conveyed to `na_level` appropriately beforehand with `df_explicit_na()` or `explicit_na()`.
+#' @describeIn abnormal_by_baseline Statistics function for a single `abnormal` level.
 #'
 #' @param na_level (`string`)\cr the explicit `na_level` argument you used in the pre-processing steps (maybe with
-#'   `df_explicit_na()`). The default is `"<Missing>"`.
+#'   [df_explicit_na()]). The default is `"<Missing>"`.
+#'
+#' @return
+#' * `s_count_abnormal_by_baseline()` returns statistic `fraction` which is a named list with 3 labeled elements:
+#'   `not_abnormal`, `abnormal`, and `total`. Each element contains a vector with `num` and `denom` patient counts.
 #'
 #' @examples
 #' df <- data.frame(
@@ -138,10 +141,11 @@ s_count_abnormal_by_baseline <- function(df,
   ))
 }
 
-#' @describeIn abnormal_by_baseline Formatted Analysis function which can be further customized by calling
-#'   [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()].
+#' @describeIn abnormal_by_baseline Formatted analysis function which is used as `afun`
+#'   in `count_abnormal_by_baseline()`.
 #'
-#' @return [a_count_abnormal_by_baseline()] returns the corresponding list with formatted [rtables::CellValue()].
+#' @return
+#' * `a_count_abnormal_by_baseline()` returns the corresponding list with formatted [rtables::CellValue()].
 #'
 #' @examples
 #' # Internal function - a_count_abnormal_by_baseline
@@ -158,10 +162,13 @@ a_count_abnormal_by_baseline <- make_afun(
   .formats = c(fraction = format_fraction)
 )
 
-#' @describeIn abnormal_by_baseline Layout creating function which can be used for creating tables, which can take
-#'   statistics function arguments and additional format arguments (see below).
+#' @describeIn abnormal_by_baseline Layout-creating function which can take statistics function arguments
+#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
 #'
-#' @inheritParams argument_convention
+#' @return
+#' * `count_abnormal_by_baseline()` returns a layout object suitable for passing to further layouting functions,
+#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing
+#'   the statistics from `s_count_abnormal_by_baseline()` to the table layout.
 #'
 #' @examples
 #' # Layout creating function.

R/abnormal_by_marked.R

@@ -2,33 +2,31 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' Primary analysis variable `.var` indicates whether single, replicated
-#' or last marked laboratory abnormality was observed (factor).
-#' Additional analysis variables are `id` (character or factor) and `direction` indicating
-#' the direction of the abnormality (factor).
-#' Denominator is number of patients with at least one valid measurement during
+#' Primary analysis variable `.var` indicates whether single, replicated or last marked laboratory
+#' abnormality was observed (`factor`). Additional analysis variables are `id` (`character` or `factor`)
+#' and `direction` (`factor`) indicating the direction of the abnormality. Denominator is number of
+#' patients with at least one valid measurement during the analysis.
 #'   * For `Single, not last` and `Last or replicated`: Numerator is number of patients
 #'     with `Single, not last` and `Last or replicated` levels, respectively.
 #'   * For `Any`: Numerator is the number of patients with either single or
 #'     replicated marked abnormalities.
 #'
-#' @details Note that `Single, not last` and `Last or replicated` levels are
-#' mutually exclusive. If a patient has abnormalities that meet both the `Single, not last`
-#' and `Last or replicated` criteria, then the patient will be counted only under the `Last or replicated` category.
-#'
 #' @inheritParams argument_convention
 #' @param category (`list`)\cr with different marked category names for single
 #'   and last or replicated.
 #'
+#' @note `Single, not last` and `Last or replicated` levels are mutually exclusive. If a patient has
+#'   abnormalities that meet both the `Single, not last` and `Last or replicated` criteria, then the
+#'   patient will be counted only under the `Last or replicated` category.
+#'
 #' @name abnormal_by_marked
 NULL
 
-#' @describeIn abnormal_by_marked Statistics function which returns
-#'   the counts and fractions of patients with `Single, not last`, `Last or replicated` and `Any`
-#'   marked laboratory abnormalities for a single `abnormal` level.
+#' @describeIn abnormal_by_marked Statistics function for patients with marked lab abnormalities.
 #'
-#' @return [s_count_abnormal_by_marked()] the single statistic `count_fraction`
-#'   with `Single, not last`, `Last or replicated` and `Any` results.
+#' @return
+#' * `s_count_abnormal_by_marked()` returns statistic `count_fraction` with `Single, not last`,
+#'   `Last or replicated`, and `Any` results.
 #'
 #' @examples
 #' library(dplyr)
@@ -133,10 +131,11 @@ s_count_abnormal_by_marked <- function(df,
   result
 }
 
-#' @describeIn abnormal_by_marked Formatted Analysis function which can be further customized by calling
-#'   [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()].
+#' @describeIn abnormal_by_marked Formatted analysis function which is used as `afun`
+#'   in `count_abnormal_by_marked()`.
 #'
-#' @return [a_count_abnormal_by_marked()] returns the corresponding list with formatted [rtables::CellValue()].
+#' @return
+#' * `a_count_abnormal_by_marked()` returns the corresponding list with formatted [rtables::CellValue()].
 #'
 #' @examples
 #' # Internal function - a_count_abnormal_by_marked
@@ -157,8 +156,13 @@ a_count_abnormal_by_marked <- make_afun(
   .formats = c(count_fraction = format_count_fraction)
 )
 
-#' @describeIn abnormal_by_marked Layout creating function which can be used for creating tables,
-#'   which can take statistics function arguments and additional format arguments (see below).
+#' @describeIn abnormal_by_marked Layout-creating function which can take statistics function arguments
+#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
+#'
+#' @return
+#' * `count_abnormal_by_marked()` returns a layout object suitable for passing to further layouting functions,
+#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing
+#'   the statistics from `s_count_abnormal_by_marked()` to the table layout.
 #'
 #' @examples
 #' map <- unique(

R/abnormal_by_worst_grade.R

@@ -2,35 +2,34 @@
 #'
 #' @description `r lifecycle::badge("stable")`
 #'
-#' Primary analysis variable `.var` indicates the toxicity grade (factor), and additional
-#' analysis variables are `id` (character or factor), `param` (`factor`) and `grade_dir` (`factor`).
+#' Primary analysis variable `.var` indicates the toxicity grade (`factor`), and additional
+#' analysis variables are `id` (`character` or `factor`), `param` (`factor`) and `grade_dir` (`factor`).
 #' The pre-processing steps are crucial when using this function.
 #' For a certain direction (e.g. high or low) this function counts
 #' patients in the denominator as number of patients with at least one valid measurement during treatment,
 #' and patients in the numerator as follows:
 #'   * `1` to `4`: Numerator is number of patients with worst grades 1-4 respectively;
 #'   * `Any`: Numerator is number of patients with at least one abnormality, which means grade is different from 0.
 #'
-#' @details
-#' The pre-processing steps are crucial when using this function. From the standard
-#' lab grade variable `ATOXGR`, derive the following two variables:
+#' @inheritParams argument_convention
+#'
+#' @details The pre-processing steps are crucial when using this function. From the standard lab grade variable
+#'   `ATOXGR`, derive the following two variables:
 #'   * A grade direction variable (e.g. `GRADE_DIR`) is required in order to obtain
 #'     the correct denominators when building the layout as it is used to define row splitting.
 #'   * A toxicity grade variable (e.g. `GRADE_ANL`) where all negative values from
 #'     `ATOXGR` are replaced by their absolute values.
-#'   * Prior to tabulation, `df` must filtered to include only post-baseline records with worst grade flags.
 #'
-#' @inheritParams argument_convention
+#' @note Prior to tabulation, `df` must be filtered to include only post-baseline records with worst grade flags.
 #'
 #' @name abnormal_by_worst_grade
 NULL
 
-#' @describeIn abnormal_by_worst_grade Statistics function which counts patients with worst grade,
-#'   consisting of counts and percentages of patients with worst grade
-#'   `1` to `4`, and `Any` non-zero grade.
+#' @describeIn abnormal_by_worst_grade Statistics function which counts patients by worst grade.
 #'
-#' @return [s_count_abnormal_by_worst_grade()] the single statistic `count_fraction` with grade 1 to 4
-#'   and "Any" results.
+#' @return
+#' * `s_count_abnormal_by_worst_grade()` returns the single statistic `count_fraction` with grades 1 to 4 and
+#'   "Any" results.
 #'
 #' @examples
 #' library(dplyr)
@@ -132,10 +131,11 @@ s_count_abnormal_by_worst_grade <- function(df, # nolint
   result
 }
 
-#' @describeIn abnormal_by_worst_grade Formatted Analysis function which can be further customized by calling
-#'   [rtables::make_afun()] on it. It is used as `afun` in [rtables::analyze()].
+#' @describeIn abnormal_by_worst_grade Formatted analysis function which is used as `afun`
+#'   in `count_abnormal_by_worst_grade()`.
 #'
-#' @return [a_count_abnormal_by_worst_grade()] returns the corresponding list with formatted [rtables::CellValue()].
+#' @return
+#' * `a_count_abnormal_by_worst_grade()` returns the corresponding list with formatted [rtables::CellValue()].
 #'
 #' @examples
 #' # Internal function - a_count_abnormal_by_worst_grade
@@ -152,8 +152,13 @@ a_count_abnormal_by_worst_grade <- make_afun( # nolint
   .formats = c(count_fraction = format_count_fraction)
 )
 
-#' @describeIn abnormal_by_worst_grade Layout creating function which can be used for creating tables,
-#'    which can take statistics function arguments and additional format arguments (see below).
+#' @describeIn abnormal_by_worst_grade Layout-creating function which can take statistics function arguments
+#'   and additional format arguments. This function is a wrapper for [rtables::analyze()].
+#'
+#' @return
+#' * `count_abnormal_by_worst_grade()` returns a layout object suitable for passing to further layouting functions,
+#'   or to [rtables::build_table()]. Adding this function to an `rtable` layout will add formatted rows containing
+#'   the statistics from `s_count_abnormal_by_worst_grade()` to the table layout.
 #'
 #' @examples
 #' # Map excludes records without abnormal grade since they should not be displayed