From ff13787566c32330ffcdf5d9c92fe55aae7547fb Mon Sep 17 00:00:00 2001
From: Emily de la Rua <59304861+edelarua@users.noreply.github.com>
Date: Wed, 31 Jan 2024 18:15:54 -0500
Subject: [PATCH] Clean up documentation for `tm_t_shift_by_grade` (#998)

Fixes #970
---
 R/tm_t_shift_by_grade.R        | 31 ++++++++++++++-----------------
 man/template_shift_by_grade.Rd |  7 +++----
 man/tm_t_shift_by_grade.Rd     | 16 +++++++++-------
 3 files changed, 26 insertions(+), 28 deletions(-)

diff --git a/R/tm_t_shift_by_grade.R b/R/tm_t_shift_by_grade.R
index 04ce46d053..a190a9d98f 100644
--- a/R/tm_t_shift_by_grade.R
+++ b/R/tm_t_shift_by_grade.R
@@ -1,16 +1,15 @@
 #' Template: Grade Summary Table
 #'
+#' Creates a valid expression to generate a grade summary table.
+#'
 #' @inheritParams template_arguments
-#' @param worst_flag_var (`character`)\cr name of the worst flag variable.
-#' @param worst_flag_indicator (`character`)\cr value indicating worst grade.
 #' @param anl_toxgrade_var (`character`)\cr name of the variable indicating the analysis toxicity grade.
-#' @param base_toxgrade_var (`character`)\cr name of the variable indicating the base toxicity grade.
-#' @param code_missing_baseline (`character`)\cr whether missing baseline should be considered
-#' as grade 0.
+#' @param base_toxgrade_var (`character`)\cr name of the variable indicating the baseline toxicity grade.
+#' @param code_missing_baseline (`logical`)\cr whether missing baseline grades should be counted as grade 0.
 #'
 #' @seealso [tm_t_shift_by_grade()]
-#' @keywords internal
 #'
+#' @keywords internal
 template_shift_by_grade <- function(parentname,
                                     dataname,
                                     arm_var = "ARM",
@@ -463,20 +462,17 @@ template_shift_by_grade <- function(parentname,
 
 #' Teal Module: Grade Summary Table
 #'
+#' This module produces a summary table of worst grades per subject by visit and parameter.
+#'
 #' @inheritParams module_arguments
 #' @inheritParams template_shift_by_grade
-#' @param visit_var ([teal.transform::choices_selected()] or [teal.transform::data_extract_spec()])\cr
-#' object with all available choices and preselected option for variable names that can be used as visit.
-#' @param worst_flag_var ([teal.transform::choices_selected()] or [teal.transform::data_extract_spec()])\cr
-#' object with all available choices and preselected option for variable names that can be used as worst flag variable.
-#' @param worst_flag_indicator ([teal.transform::choices_selected()] or [teal.transform::data_extract_spec()])\cr
-#' value indicating worst grade.
 #' @param anl_toxgrade_var ([teal.transform::choices_selected()] or [teal.transform::data_extract_spec()])\cr
-#' variable for analysis toxicity grade.
+#'   variable for analysis toxicity grade.
 #' @param base_toxgrade_var ([teal.transform::choices_selected()] or [teal.transform::data_extract_spec()])\cr
-#' variable for baseline toxicity grade.
+#'   variable for baseline toxicity grade.
+#'
+#' @return a [teal::module()] object which can be added to a `teal` app via [teal::init()].
 #'
-#' @export
 #' @examples
 #' ADSL <- tmc_ex_adsl
 #' ADLB <- tmc_ex_adlb
@@ -529,6 +525,7 @@ template_shift_by_grade <- function(parentname,
 #'   shinyApp(app$ui, app$server)
 #' }
 #'
+#' @export
 tm_t_shift_by_grade <- function(label,
                                 dataname,
                                 parentname = ifelse(
@@ -624,7 +621,7 @@ tm_t_shift_by_grade <- function(label,
   )
 }
 
-#' @noRd
+#' @keywords internal
 ui_t_shift_by_grade <- function(id, ...) {
   ns <- shiny::NS(id)
   a <- list(...) # module args
@@ -731,7 +728,7 @@ ui_t_shift_by_grade <- function(id, ...) {
   )
 }
 
-#' @noRd
+#' @keywords internal
 srv_t_shift_by_grade <- function(id,
                                  data,
                                  reporter,
diff --git a/man/template_shift_by_grade.Rd b/man/template_shift_by_grade.Rd
index 0959d9624c..33a2e46275 100644
--- a/man/template_shift_by_grade.Rd
+++ b/man/template_shift_by_grade.Rd
@@ -41,7 +41,7 @@ template_shift_by_grade(
 
 \item{anl_toxgrade_var}{(\code{character})\cr name of the variable indicating the analysis toxicity grade.}
 
-\item{base_toxgrade_var}{(\code{character})\cr name of the variable indicating the base toxicity grade.}
+\item{base_toxgrade_var}{(\code{character})\cr name of the variable indicating the baseline toxicity grade.}
 
 \item{paramcd}{(\code{character})\cr variable value designating the studied parameter.}
 
@@ -55,8 +55,7 @@ When \code{TRUE}, \code{arm_var} levels are set to those used in the \code{datan
 in character or factor variables in the data. Defaults to \code{"<Missing>"}. To set a
 default \code{na_level} to apply in all modules, run \code{set_default_na_str("new_default")}.}
 
-\item{code_missing_baseline}{(\code{character})\cr whether missing baseline should be considered
-as grade 0.}
+\item{code_missing_baseline}{(\code{logical})\cr whether missing baseline grades should be counted as grade 0.}
 
 \item{basic_table_args}{optional, (\code{basic_table_args})\cr object created by \code{\link[teal.widgets:basic_table_args]{teal.widgets::basic_table_args()}}
 with settings for the module table. The argument is merged with option \code{teal.basic_table_args} and with default
@@ -65,7 +64,7 @@ module arguments (hard coded in the module body).
 For more details, see the vignette: \code{vignette("custom-basic-table-arguments", package = "teal.widgets")}.}
 }
 \description{
-Template: Grade Summary Table
+Creates a valid expression to generate a grade summary table.
 }
 \seealso{
 \code{\link[=tm_t_shift_by_grade]{tm_t_shift_by_grade()}}
diff --git a/man/tm_t_shift_by_grade.Rd b/man/tm_t_shift_by_grade.Rd
index 4c434266ea..e038da5976 100644
--- a/man/tm_t_shift_by_grade.Rd
+++ b/man/tm_t_shift_by_grade.Rd
@@ -50,13 +50,13 @@ It defines the grouping variable(s) in the results table.
 If there are two elements selected for \code{arm_var},
 second variable will be nested under the first variable.}
 
-\item{visit_var}{(\code{\link[teal.transform:choices_selected]{teal.transform::choices_selected()}} or \code{\link[teal.transform:data_extract_spec]{teal.transform::data_extract_spec()}})\cr
-object with all available choices and preselected option for variable names that can be used as visit.}
+\item{visit_var}{(\code{choices_selected} or \code{data_extract_spec})\cr object with all available choices and preselected
+option for variable names that can be used as \code{visit} variable. Must be a factor in \code{dataname}.}
 
 \item{paramcd}{(\code{choices_selected} or \code{data_extract_spec})\cr variable value designating the studied parameter.}
 
-\item{worst_flag_var}{(\code{\link[teal.transform:choices_selected]{teal.transform::choices_selected()}} or \code{\link[teal.transform:data_extract_spec]{teal.transform::data_extract_spec()}})\cr
-object with all available choices and preselected option for variable names that can be used as worst flag variable.}
+\item{worst_flag_var}{(\code{\link[teal.transform:choices_selected]{teal.transform::choices_selected()}} or \code{\link[teal.transform:data_extract_spec]{teal.transform::data_extract_spec()}})\cr object
+with all available choices and preselected option for variable names that can be used as worst flag variable.}
 
 \item{worst_flag_indicator}{(\code{\link[teal.transform:choices_selected]{teal.transform::choices_selected()}} or \code{\link[teal.transform:data_extract_spec]{teal.transform::data_extract_spec()}})\cr
 value indicating worst grade.}
@@ -89,8 +89,7 @@ For example the \code{\link[shiny:helpText]{shiny::helpText()}} elements are use
 in character or factor variables in the data. Defaults to \code{"<Missing>"}. To set a
 default \code{na_level} to apply in all modules, run \code{set_default_na_str("new_default")}.}
 
-\item{code_missing_baseline}{(\code{character})\cr whether missing baseline should be considered
-as grade 0.}
+\item{code_missing_baseline}{(\code{logical})\cr whether missing baseline grades should be counted as grade 0.}
 
 \item{basic_table_args}{optional, (\code{basic_table_args})\cr object created by \code{\link[teal.widgets:basic_table_args]{teal.widgets::basic_table_args()}}
 with settings for the module table. The argument is merged with option \code{teal.basic_table_args} and with default
@@ -98,8 +97,11 @@ module arguments (hard coded in the module body).
 
 For more details, see the vignette: \code{vignette("custom-basic-table-arguments", package = "teal.widgets")}.}
 }
+\value{
+a \code{\link[teal:module]{teal::module()}} object which can be added to a \code{teal} app via \code{\link[teal:init]{teal::init()}}.
+}
 \description{
-Teal Module: Grade Summary Table
+This module produces a summary table of worst grades per subject by visit and parameter.
 }
 \examples{
 ADSL <- tmc_ex_adsl