feat: unifying documentation

Author: averissimo

R/roxygen2_templates.R

@@ -0,0 +1,30 @@
+# nocov start
+roxygen_decorators_param <- function(module_name) {
+  paste(
+    sep = " ",
+    lifecycle::badge("experimental"),
+    " (`list` of `teal_transform_module`, named `list` of `teal_transform_module` or",
+    "`NULL`) optional, if not `NULL`, decorator for tables or plots included in the module.",
+    "When a named list of `teal_transform_module`, the decorators are applied to the",
+    "respective output objects.\n\n",
+    "Otherwise, the decorators are applied to all objects, which is equivalent as using the name `default`.\n\n",
+    sprintf("See section \"Decorating `%s`\"", module_name),
+    "below for more details."
+  )
+}
+
+roxygen_ggplot2_args_param <- function(...) {
+  paste(
+    sep = " ",
+    "(`ggplot2_args`) optional, object created by [`teal.widgets::ggplot2_args()`]",
+    "with settings for all the plots or named list of `ggplot2_args` objects for plot-specific settings.",
+    "The argument is merged with options variable `teal.ggplot2_args` and default module setup.\n\n",
+    sprintf(
+      "List names should match the following: `c(\"default\", %s)`.\n\n",
+      paste("\"", unlist(rlang::list2(...)), "\"", collapse = ", ", sep = "")
+    ),
+    "For more details see the vignette: `vignette(\"custom-ggplot2-arguments\", package = \"teal.widgets\")`."
+  )
+}
+
+# nocov end

R/tm_a_pca.R

@@ -13,8 +13,8 @@
 #' It controls the font size for plot titles, axis labels, and legends.
 #' - If vector of `length == 1` then the font sizes will have a fixed size.
 #' - while vector of `value`, `min`, and `max` allows dynamic adjustment.
-#' @templateVar ggnames "Elbow plot", "Circle plot", "Biplot", "Eigenvector plot"
-#' @template ggplot2_args_multi
+#' @param ggplot2_args `r roxygen_ggplot2_args_param("Elbow plot", "Circle plot", "Biplot", "Eigenvector plot")`
+#' @param decorators `r roxygen_decorators_param("tm_a_pca")`
 #'
 #' @inherit shared_params return
 #'

R/tm_a_regression.R

@@ -37,8 +37,8 @@
 #'     It takes the form of `c(value, min, max)` and it is passed to the `value_min_max`
 #'     argument in `teal.widgets::optionalSliderInputValMinMax`.
 #'
-#' @templateVar ggnames `r regression_names`
-#' @template ggplot2_args_multi
+#' @param ggplot2_args `r roxygen_ggplot2_args_param(regression_names)`
+#' @param decorators `r roxygen_decorators_param("tm_a_regression")`
 #'
 #' @inherit shared_params return
 #'
@@ -1035,7 +1035,10 @@ srv_a_regression <- function(id,
   })
 }
 
-regression_names <- paste0(
-  '"Response vs Regressor", "Residuals vs Fitted", ',
-  '"Scale-Location", "Cook\'s distance", "Residuals vs Leverage"", "Cook\'s dist vs Leverage"'
+regression_names <- c(
+  "Response vs Regressor",
+  "Residuals vs Fitted",
+  "Scale-Location", "Cook's distance",
+  "Residuals vs Leverage",
+  "Cook's dist vs Leverage"
 )

R/tm_g_association.R

@@ -20,8 +20,8 @@
 #' @param distribution_theme,association_theme (`character`) optional, `ggplot2` themes to be used by default.
 #' Default to `"gray"`.
 #'
-#' @templateVar ggnames "Bivariate1", "Bivariate2"
-#' @template ggplot2_args_multi
+#' @param ggplot2_args `r roxygen_ggplot2_args_param("Bivariate1", "Bivariate2")`
+#' @param decorators `r roxygen_decorators_param("tm_")`
 #'
 #' @inherit shared_params return
 #'

R/tm_g_distribution.R

@@ -22,8 +22,8 @@
 #' and `max`.
 #' Defaults to `c(30L, 1L, 100L)`.
 #'
-#' @templateVar ggnames "Histogram", "QQplot"
-#' @template ggplot2_args_multi
+#' @param ggplot2_args `r roxygen_ggplot2_args_param("Histogram", "QQplot")`
+#' @param decorators `r roxygen_decorators_param("tm_g_distribution")`
 #'
 #' @inherit shared_params return
 #'
@@ -34,17 +34,19 @@
 #' - `test_table` (`data.frame`)
 #' - `summary_table` (`data.frame`)
 #'
-#' The `decorators` can be specific for the `histogram` and `decorators` outputs
-#' within the module, which can be specified by using a named list.
+#' Decorators can be applied to all outputs or only to specific objects using a
+#' named list of `teal_transform_module` objects.
+#' The `"default"` name is reserved for decorators that are applied to all outputs.
 #' See code snippet below:
 #'
 #' ```
 #' tm_g_distribution(
 #'    ..., # arguments for module
 #'    decorators = list(
-#'      default = list(teal_transform_module(...)), # applied to outputs of both `histogram` and `qq`
-#'      histogram = list(teal_transform_module(...)), # applied to outputs of `histogram`
-#'      qq = list(teal_transform_module(...)) # applied to outputs of `qq`
+#'      default = list(teal_transform_module(...)), # applied to all outputs
+#'      plot = list(teal_transform_module(...)), # applied only to plot output (histogram plot)
+#'      test_table = list(teal_transform_module(...)) # applied only to test_table
+#'      summary_table = list(teal_transform_module(...)) # applied only to summary_table
 #'    )
 #' )
 #' ```

R/tm_missing_data.R

@@ -12,8 +12,8 @@
 #' ignored.
 #' @param ggtheme (`character`) optional, specifies the default `ggplot2` theme for plots. Defaults to `classic`.
 #'
-#' @templateVar ggnames "Summary Obs", "Summary Patients", "Combinations Main", "Combinations Hist", "By Subject"
-#' @template ggplot2_args_multi
+#' @param ggplot2_args `r roxygen_ggplot2_args_param(missing_data_names)`
+#' @param decorators `r roxygen_decorators_param("tm_missing_data")`
 #'
 #' @inherit shared_params return
 #'
@@ -1393,3 +1393,7 @@ srv_missing_data <- function(id,
     ###
   })
 }
+
+missing_data_names <- c(
+  "Summary Obs", "Summary Patients", "Combinations Main", "Combinations Hist", "By Subject"
+)

R/tm_outliers.R

@@ -11,9 +11,8 @@
 #' Specifies variable(s) to be analyzed for outliers.
 #' @param categorical_var (`data_extract_spec` or `list` of multiple `data_extract_spec`) optional,
 #' specifies the categorical variable(s) to split the selected outlier variables on.
-#'
-#' @templateVar ggnames "Boxplot","Density Plot","Cumulative Distribution Plot"
-#' @template ggplot2_args_multi
+#' @param decorators `r roxygen_decorators_param("tm_outliers")`
+#' @param ggplot2_args `r roxygen_ggplot2_args_param("Boxplot", "Density Plot", "Cumulative Distribution Plot")`
 #'
 #' @inherit shared_params return
 #'

R/utils.R

@@ -25,20 +25,6 @@
 #'  with text placed before the output to put the output into context. For example a title.
 #' @param post_output (`shiny.tag`) optional, text or UI element to be displayed after the module's output,
 #' adding context or further instructions. Elements like `shiny::helpText()` are useful.
-#' @param decorators `r lifecycle::badge("experimental")`
-#' (`list` of `teal_transform_module`,
-#' named `list` of `teal_transform_module` or
-#' `NULL`) optional,
-#' if not `NULL`, decorator for tables or plots included in the module.
-#' When a named list of `teal_transform_module`, the decorators are applied to the
-#' outputs of the corresponding view of the module.
-#' Otherwise, the decorators are applied to all outputs in all views equally, which is the same
-#' as using the name `default`.
-#'
-#' A module can have different views with different outputs, such as a tab with
-#' a table and another with a plot.
-#' See section "Decorating `tm_<module_name>`" below for more details.
-#'
 #' @param alpha (`integer(1)` or `integer(3)`) optional, specifies point opacity.
 #' - When the length of `alpha` is one: the plot points will have a fixed opacity.
 #' - When the length of `alpha` is three: the plot points opacity are dynamically adjusted based on