Check roxygen documentation (#168)

**What changes are proposed in this pull request?**
* Check all function documentation to ensure `@return` and `@examples`
fields are present, no missing documentation pages, no typos, and
consistent documentation of parameters. Also added function links where
applicable.

This PR is pretty big - I can break it up if you prefer to review
smaller pieces at a time!

Closes #149 



--------------------------------------------------------------------------------

Pre-review Checklist (if item does not apply, mark is as complete)
- [x] **All** GitHub Action workflows pass with a ✅
- [x] PR branch has pulled the most recent updates from master branch:
`usethis::pr_merge_main()`
- [x] If a bug was fixed, a unit test was added.
- [x] Code coverage is suitable for any new functions/features
(generally, 100% coverage for new code): `devtools::test_coverage()`
- [x] Request a reviewer

Reviewer Checklist (if item does not apply, mark is as complete)

- [x] If a bug was fixed, a unit test was added.
- [x] Run `pkgdown::build_site()`. Check the R console for errors, and
review the rendered website.
- [x] Code coverage is suitable for any new functions/features:
`devtools::test_coverage()`

When the branch is ready to be merged:
- [x] Update `NEWS.md` with the changes from this pull request under the
heading "`# cards (development version)`". If there is an issue
associated with the pull request, reference it in parentheses at the end
update (see `NEWS.md` for examples).
- [x] **All** GitHub Action workflows pass with a ✅
- [x] Approve Pull Request
- [x] Merge the PR. Please use "Squash and merge" or "Rebase and merge".

R/apply_statistic_fmt_fn.R

@@ -1,12 +1,12 @@
 #' Apply Formatting Functions
 #'
 #' Apply the formatting functions to each of the raw statistics.
-#' Function aliases are converted to functions using `alias_as_fmt_fn()`.
+#' Function aliases are converted to functions using [alias_as_fmt_fn()].
 #'
 #' @param x (`data.frame`)\cr
 #'   an ARD data frame of class 'card'
 #'
-#' @return an ARD data frame
+#' @return an ARD data frame of class 'card'
 #' @export
 #'
 #' @examples
@@ -52,8 +52,10 @@ apply_statistic_fmt_fn <- function(x) {
 #' spaces that are added to the result.
 #' If the string ends in `"%"`, results are scaled by 100 before rounding.
 #'
-#' @param x a non-negative integer, string alias, or function
-#' @param call call environment for error messaging
+#' @param x (`integer`, `string`, or `function`)\cr
+#'   a non-negative integer, string alias, or function
+#' @param call (`environment`)\cr
+#'   frame for error messaging. Default is [parent.frame()].
 #'
 #' @return a function
 #' @export
@@ -95,11 +97,14 @@ alias_as_fmt_fn <- function(x, call = parent.frame()) {
 #'
 #' Returns a function with the requested rounding and scaling schema.
 #'
-#' @param digits a non-negative integer specifying the number of decimal places
+#' @param digits (`integer`)\cr
+#'   a non-negative integer specifying the number of decimal places
 #'   round statistics to
-#' @param scale a scalar real number.
-#'   Before rounding, the input will be scaled by this quantity.
-#' @param width a non-negative integer specifying the minimum width of the
+#' @param scale (`numeric`)\cr
+#'   a scalar real number. Before rounding, the input will be scaled by
+#'   this quantity
+#' @param width (`integer`)\cr
+#'   a non-negative integer specifying the minimum width of the
 #'   returned formatted values
 #'
 #' @return a function
@@ -138,11 +143,12 @@ label_cards <- function(digits = 1, scale = 1, width = NULL) {
 #'
 #' If string is consistent, `TRUE` is returned. Otherwise an error.
 #'
+#' @param x (`string`)\cr
+#'   string to check
+#' @param call (`environment`)\cr
+#'   frame for error messaging. Default is [caller_env()].
 #'
-#' @param x string to check
-#' @param call calling environment. Default is `caller_env()`
-#'
-#' @return logical
+#' @return a logical
 #' @keywords internal
 #'
 #' @examples

R/ard_attributes.R

@@ -15,7 +15,7 @@
 #' @param variables ([`tidy-select`][dplyr::dplyr_tidy_select])\cr
 #'   variables to include
 #'
-#' @return a data frame
+#' @return an ARD data frame of class 'card'
 #' @export
 #'
 #' @examples

R/ard_categorical.R

@@ -3,9 +3,9 @@
 #' Compute Analysis Results Data (ARD) for categorical summary statistics.
 #'
 #' @param data (`data.frame`)\cr
-#' a data frame
+#'   a data frame
 #' @param by,strata ([`tidy-select`][dplyr::dplyr_tidy_select])\cr
-#'   columns to by/stratified by for tabulation.
+#'   columns to tabulate by/stratify by for tabulation.
 #'   Arguments are similar, but with an important distinction:
 #'
 #'   `by`: results are tabulated by **all combinations** of the columns specified,
@@ -17,7 +17,7 @@
 #'   Arguments may be used in conjunction with one another.
 #' @param variables ([`tidy-select`][dplyr::dplyr_tidy_select])\cr
 #'   columns to include in summaries. Default is `everything()`.
-#' @param denominator (`data.frame`, `integer()`)\cr
+#' @param denominator (`data.frame`, `integer`)\cr
 #'   Specify this *optional* argument to change the denominator,
 #'   e.g. the `"N"` statistic. Default is `NULL`. See below for details.
 #' @param statistics ([`formula-list-selector`][syntax])\cr
@@ -33,8 +33,8 @@
 #' @inheritParams ard_continuous
 #'
 #' @section Denominators:
-#' By default, the `ard_categorical()` function returns the statistics `"n"` and `"N"`,
-#' where little `"n"` are the counts for the variable levels, and `"N"` is
+#' By default, the `ard_categorical()` function returns the statistics `"n"`, `"N"`, and
+#' `"p"`, where little `"n"` are the counts for the variable levels, and big `"N"` is
 #' the number of non-missing observations. The default calculation for the
 #' percentage is merely `p = n/N`.
 #'
@@ -45,20 +45,20 @@
 #'
 #' In such cases, use the `denominator` argument to specify a new definition
 #' of `"N"`, and subsequently `"p"`.
-#' The argument expects the following inputs:
+#' The argument expects one of the following inputs:
 #' - a data frame. Any columns in the data frame that overlap with the `by`/`strata`
 #'   columns will be used to calculate the new `"N"`.
 #' - an integer. This single integer will be used as the new `"N"`
-#' - a string: one of `c("column", "row", "cell")`. `"column"` is equivalent
+#' - a string: one of `"column"`, `"row"`, or `"cell"`. `"column"` is equivalent
 #'   to `denominator=NULL`. `"row"` gives 'row' percentages where `by`/`strata`
-#'   columns are are the 'top' of a cross table, and the variables are the rows.
+#'   columns are the 'top' of a cross table, and the variables are the rows.
 #'   `"cell"` gives percentages where the denominator is the number of non-missing
 #'   rows in the source data frame.
 #' - a structured data frame. The data frame will include columns from `by`/`strata`.
 #'   The last column must be named `"...ard_N..."`. The integers in this column will
 #'   be used as the updated `"N"` in the calculations.
 #'
-#' @return a data frame
+#' @return an ARD data frame of class 'card'
 #' @export
 #'
 #' @examples
@@ -184,7 +184,18 @@ ard_categorical <- function(data,
 #' argument, and returns the tabulations in an ARD structure.
 #'
 #' @inheritParams ard_categorical
+#' @return an ARD data frame of class 'card'
 #' @keywords internal
+#'
+#' @examples
+#' cards:::.calculate_tabulation_statistics(
+#'   ADSL,
+#'   variables = "ARM",
+#'   by = NULL,
+#'   strata = NULL,
+#'   denominator = "cell",
+#'   statistics = list(ARM = list(tabulation = c("N")))
+#' )
 .calculate_tabulation_statistics <- function(data, variables, by, strata, denominator, statistics, call = parent.frame()) {
   # extract the "tabulation" statistics.
   statistics_tabulation <-
@@ -276,19 +287,26 @@ ard_categorical <- function(data,
 
 #' Results from `table()` as Data Frame
 #'
-#' Takes the results from `table()` and returns them as a data frame.
-#' After the `table()` results are made into a data frame, all the variables
+#' Takes the results from [table()] and returns them as a data frame.
+#' After the [table()] results are made into a data frame, all the variables
 #' are made into character columns, and the function also restores the
 #' column types to their original classes. For `strata` columns,
 #' only observed combinations are returned.
 #'
-#' @param data a data frame
-#' @param variable a string indicating a column in data
-#' @param by a character vector indicating columns in data
-#' @param strata a character vector indicating columns in data
+#' @param data (`data.frame`)\cr
+#'   a data frame
+#' @param variable (`string`)\cr
+#'   a string indicating a column in data
+#' @param by (`character`)\cr
+#'   a character vector indicating columns in data
+#' @param strata (`character`)\cr
+#'   a character vector indicating columns in data
 #'
 #' @keywords internal
 #' @return data frame
+#'
+#' @examples
+#' cards:::.table_as_df(ADSL, variable = "ARM", by = "AGEGR1", strata = NULL)
 .table_as_df <- function(data, variable = NULL, by = NULL, strata = NULL, count_column = "...ard_n...") {
   # tabulate results and save in data frame
   ...ard_tab_vars... <- c(by, strata, variable)
@@ -327,17 +345,18 @@ ard_categorical <- function(data,
 }
 
 
-#' Process Denominator Argument
+#' Process `denominator` Argument
 #'
 #' Function takes the `ard_categorical(denominator)` argument and returns a
 #' structured data frame that is merged with the count data and used as the
 #' denominator in percentage calculations.
 #'
 #' @inheritParams ard_categorical
-#' @param env env used in error reporting.
+#' @param call (`environment`)\cr
+#'   frame for error messaging. Default is [parent.frame()].
 #'
+#' @return a data frame
 #' @keywords internal
-#' @return data frame
 #'
 #' @examples
 #' cards:::.process_denominator(mtcars, denominator = 1000, variables = "cyl", by = "gear")
@@ -473,20 +492,28 @@ ard_categorical <- function(data,
 
 
 
-#' Check for missing levels in `denominator`
+#' Check for Missing Levels in `denominator`
 #'
 #' When a user passes a data frame in the `denominator` argument, this function
 #' checks that the data frame contains all the same levels of the `by`
-#' and `strata` variables that appear in the `data`
+#' and `strata` variables that appear in `data`.
 #'
-#' @param data data frame
-#' @param denominator denominator data frame
-#' @param by character vector of by column names
-#' @param strata character vector of strata column names
-#' @param env environment for error messaging
+#' @param data (`data.frame`)\cr
+#'   a data frame
+#' @param denominator (`data.frame`)\cr
+#'   denominator data frame
+#' @param by (`character`)\cr
+#'   character vector of by column names
+#' @param strata (`character`)\cr
+#'   character vector of strata column names
+#' @param call (`environment`)\cr
+#'   frame for error messaging. Default is [parent.frame()].
 #'
-#' @return invisible
+#' @return returns invisible if check is successful, throws an error message if not.
 #' @keywords internal
+#'
+#' @examples
+#' cards:::.check_for_missing_combos_in_denom(ADSL, denominator = "col", by = "ARM", strata = "AGEGR1")
 .check_for_missing_combos_in_denom <- function(data, denominator, by, strata, call = parent.frame()) {
   by_vars_to_check <-
     c(by, strata) |>

R/ard_complex.R

@@ -1,28 +1,28 @@
 #' Complex ARD Summaries
 #'
 #' `r lifecycle::badge('experimental')`\cr
-#' Function is similar to `ard_continuous()`, but allows for more complex
+#' Function is similar to [ard_continuous()], but allows for more complex
 #' summaries. While `ard_continuous(statistics)` only allows for a univariable
 #' function, `ard_complex(statistics)` can handle more complex data summaries.
 #'
 #' @inheritParams ard_continuous
 #' @param statistics ([`formula-list-selector`][syntax])\cr
 #'   The form of the statistics argument is identical to `ard_continuous(statistics)`
-#'   argument, except the summary function _must_ accept the following arguments.
-#'   - `x` vector
-#'   - `data` the data frame that has been subset by the `by`/`strata` columns
+#'   argument, except the summary function _must_ accept the following arguments:
+#'   - `x`: a vector
+#'   - `data`: the data frame that has been subset such that the `by`/`strata` columns
 #'       and rows in which `"variable"` is `NA` have been removed.
-#'   - `data_full` the full data frame
-#'   - `by` character vector of the `by` variables
-#'   - `strata` character vector of the `strata` variables
+#'   - `data_full`: the full data frame
+#'   - `by`: character vector of the `by` variables
+#'   - `strata`: character vector of the `strata` variables
 #'   It is unlikely any one function will need _all_ of the above elements,
-#'   and it's recommended the function passed accepts `...` and any unused
+#'   and it's recommended the function passed accepts `...` so that any unused
 #'   arguments will be properly ignored. The `...` also allows this function
 #'   to perhaps be updated in the future with more passed arguments. For example,
 #'   if one needs a second variable from the data frame, the function inputs
 #'   may look like: `foo(x, data, ...)`
 #'
-#' @return a data frame
+#' @return an ARD data frame of class 'card'
 #' @export
 #'
 #' @examples
@@ -34,7 +34,7 @@
 #'   statistics = list(AGE = list(mean = \(x, ...) mean(x)))
 #' )
 #'
-#' # return the grand mean and the mean within the by group
+#' # return the grand mean and the mean within the `by` group
 #' grand_mean <- function(data, data_full, variable, ...) {
 #'   list(
 #'     mean = mean(data[[variable]], na.rm = TRUE),