docs: standardize roxygen tag @return to @returns across R/ (#1363)

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: aNCA
 Title: (Pre-)Clinical NCA in a Dynamic Shiny App
-Version: 0.1.0.9188
+Version: 0.1.0.9189
 Authors@R: c(
     person("Ercan", "Suekuer", email = "ercan.suekuer@roche.com", role = "aut",
            comment = c(ORCID = "0009-0001-1626-1526")),

NEWS.md

@@ -75,6 +75,7 @@
 * SelectInputs updated to include variable labels (#899)
 
 ### Documentation & UI
+* Standardized documentation tag `@return` to `@returns` across R/ for consistency with project convention (#1363)
 * UI consistency pass: standardized dropdown labels to "Select the...", help button placement to right-aligned, "colour" to "color", renamed Save to "Export as ZIP", simplified download button text, and added "Short Parameter"/"Specimen" columns to Units table (#1333)
 * Searchable PK parameter reference table in NCA > Setup (#1023)
 * R Script Walkthrough vignette added to pkgdown website (#1090)

R/PKNCA.R

@@ -846,7 +846,7 @@ PKNCA_hl_rules_exclusion <- function(res, rules) { # nolint
 #' @param processed_pknca_data A processed PKNCA data object.
 #' @param check_exclusion_has_reason Logical; Check if all exclusions have a reason (default: TRUE).
 #'
-#' @return The processed_pknca_data object (input), if checks are successful.
+#' @returns The processed_pknca_data object (input), if checks are successful.
 #'
 #' @details
 #' - If any excluded half-life points are missing a reason, an error is thrown.
@@ -888,7 +888,7 @@ check_valid_pknca_data <- function(processed_pknca_data, check_exclusion_has_rea
 #' using a pivoted approach.
 #'
 #' @param pknca_res A PKNCA results object containing at least $data$intervals and $result.
-#' @return The PKNCA results object with non requested parameters removed from $result.
+#' @returns The PKNCA results object with non requested parameters removed from $result.
 #' @export
 remove_pp_not_requested <- function(pknca_res) {
   params <- c(setdiff(names(PKNCA::get.interval.cols()), c("start", "end")))
@@ -934,7 +934,7 @@ remove_pp_not_requested <- function(pknca_res) {
 #'     PKSUM1F = "Y" and the reason is stored in PKSUM1RS so
 #'     TLGs can filter them out
 #'
-#' @return The modified PKNCAdata object with updated exclusion
+#' @returns The modified PKNCAdata object with updated exclusion
 #'   reasons, PKSUM1F, and PKSUM1RS in the concentration object.
 #' @export
 add_exclusion_reasons <- function(pknca_data, exclusion_list) {

R/PKNCA_extra_parameters.R

@@ -5,7 +5,7 @@
 #' @param time The starting time of the collection interval
 #' @param duration.conc The duration of the collection interval
 #' @param check Should the concentration and time data be checked?
-#' @return The midpoint collection time of the last measurable excretion rate, or NA/0 if not available
+#' @returns The midpoint collection time of the last measurable excretion rate, or NA/0 if not available
 #' @export
 pk.calc.ertlst <- function(conc, volume, time, duration.conc, check = TRUE) {
 
@@ -51,7 +51,7 @@ PKNCA::PKNCA.set.summary(
 #' @param time The starting time of the collection interval
 #' @param duration.conc The duration of the collection interval
 #' @param check Should the concentration data be checked?
-#' @return The maximum excretion rate, or NA if not available
+#' @returns The maximum excretion rate, or NA if not available
 #' @export
 pk.calc.ermax <- function(conc, volume, time, duration.conc, check = TRUE) {
 
@@ -83,7 +83,7 @@ pk.calc.ermax <- function(conc, volume, time, duration.conc, check = TRUE) {
 #' @param check Should the concentration and time data be checked?
 #' @param first.tmax If TRUE, return the first time of maximum excretion rate; otherwise, return the last
 #' @param options List of PKNCA global options set
-#' @return The midpoint collection time of the maximum excretion rate, or NA if not available
+#' @returns The midpoint collection time of the maximum excretion rate, or NA if not available
 #' @export
 pk.calc.ertmax <- function( #nolint
     conc, volume, time, duration.conc, check = TRUE, first.tmax = NULL, options = list() #nolint
@@ -189,7 +189,7 @@ generate_missing_messages <- function(a, b,
 #' Calculate the total urine volume
 #'
 #' @param volume The volume (or mass) of the sample
-#' @return The sum of urine volumes for the interval
+#' @returns The sum of urine volumes for the interval
 #' @export
 pk.calc.volpk <- function(volume) { #nolint
   if (length(volume) == 0) return(NA_real_)

R/exploration_plots.R

@@ -30,7 +30,7 @@
 #' @param line_type Character; "default" (default), "dose-normalized" to specify lines to
 #' be normalized by dose amount or "both" to include both normalized and non-normalized lines.
 #'
-#' @return A `ggplot` object representing the individual PK line plot.
+#' @returns A `ggplot` object representing the individual PK line plot.
 #' @export
 exploration_individualplot <- function(
   pknca_data,
@@ -110,7 +110,7 @@ exploration_individualplot <- function(
 #' Default is `NULL` (no limits).
 #' @param y_limits Numeric vector of length 2 for y-axis limits (min, max).
 #' Default is `NULL` (no limits).
-#' @return A `ggplot` object representing the mean PK line plot,
+#' @returns A `ggplot` object representing the mean PK line plot,
 #' with error bars and/or confidence intervals if requested.
 #' @export
 exploration_meanplot <- function(
@@ -215,7 +215,7 @@ exploration_meanplot <- function(
 #' @param use_time_since_last_dose Logical; if `TRUE`, x-axis represents time since last dose.
 #' Default is `FALSE` (time since first dose).
 #'
-#' @return Data frame filtered and ready for individual spaghetti plots,
+#' @returns Data frame filtered and ready for individual spaghetti plots,
 #' with optional TIME_DOSE column.
 #' @importFrom dplyr filter mutate
 #' @importFrom rlang sym
@@ -294,7 +294,7 @@ process_data_individual <- function(pknca_data,
 #' @param use_time_since_last_dose Logical; if `TRUE`, x-axis represents time since last dose.
 #' Default is `FALSE` (time since first dose).
 #'
-#' @return Data frame summarised by group, with columns for Mean, SD, N, SE, SD_min, SD_max,
+#' @returns Data frame summarised by group, with columns for Mean, SD, N, SE, SD_min, SD_max,
 #' CI_lower, CI_upper, and optional TIME_DOSE.
 #' @importFrom dplyr group_by summarise filter mutate n n_distinct distinct left_join select
 #' @importFrom rlang sym syms
@@ -447,7 +447,7 @@ process_data_mean <- function(pknca_data,
 #' @param filtering_list A named list where each name is a column and each value is a vector
 #' of allowed values.
 #'
-#' @return Filtered data frame.
+#' @returns Filtered data frame.
 #' @keywords internal
 #' @noRd
 filter_by_list <- function(data, filtering_list) {
@@ -471,7 +471,7 @@ filter_by_list <- function(data, filtering_list) {
 #' @param y_var Name of the y variable.
 #' @param x_var Name of the x variable.
 #'
-#' @return Finalized ggplot object for mean PK plot.
+#' @returns Finalized ggplot object for mean PK plot.
 #' @keywords internal
 #' @noRd
 finalize_meanplot <- function(plot, sd_min, sd_max, ci, color_by, y_var, x_var) {
@@ -511,7 +511,7 @@ finalize_meanplot <- function(plot, sd_min, sd_max, ci, color_by, y_var, x_var)
 #' @param conc_time_col Name of the time column in concentration data.
 #' Default is pknca_data$conc$columns$time.
 #'
-#' @return Data frame with TIME_DOSE column added, representing the last dose time for each sample.
+#' @returns Data frame with TIME_DOSE column added, representing the last dose time for each sample.
 #' @importFrom dplyr left_join mutate select any_of filter group_by arrange slice_tail ungroup
 #' @importFrom rlang sym syms
 #' @keywords internal

R/export_cdisc.R

@@ -548,7 +548,7 @@ add_derived_pp_vars <- function(df, conc_group_sp_cols, conc_timeu_col, dose_tim
 ##' @param data A data.frame containing the exclusion column.
 ##' @param nca_excl_colname Character name of the column in `data` that holds
 ##'   semicolon-separated exclusion reasons.
-##' @return The input `data` with new `NCA<n>XRS`, `NCA<n>XRSN`, `NCAXFL`, and
+##' @returns The input `data` with new `NCA<n>XRS`, `NCA<n>XRSN`, `NCAXFL`, and
 ##'   `NCAXFN` columns added; the original exclusion column is removed.
 ##' @noRd
 ##' @keywords internal

R/filter_breaks.R

@@ -6,7 +6,7 @@
 #' @param plot            A ggplot object used to extract plot dimensions and scales.
 #' @param min_cm_distance A numeric of the minimum distance between breaks.
 #' @param axis            Axis to filter on, either "x" or "y".
-#' @return A numeric vector of filtered x-axis breaks.
+#' @returns A numeric vector of filtered x-axis breaks.
 #' @importFrom ggplot2 ggplot_build ggplot_gtable
 #' @importFrom grid convertUnit
 #' @importFrom stats na.omit

R/flexible_violinboxplot.R

@@ -23,7 +23,7 @@
 #'                            `exclude` column) are overlaid as cross-shaped points. They are
 #'                            never included in box/violin statistics. Default is `FALSE`.
 #'
-#' @return A plotly object representing the violin or box plot.
+#' @returns A plotly object representing the violin or box plot.
 #' @import dplyr
 #' @import ggplot2
 #' @export
@@ -229,7 +229,7 @@ flexible_violinboxplot <- function(res_nca,
 #'
 #' @param box_data Data frame to check.
 #' @param parameter Parameter name for error message context.
-#' @return NULL if valid, or a ggplot error plot if invalid.
+#' @returns NULL if valid, or a ggplot error plot if invalid.
 #' @noRd
 .check_boxplot_data <- function(box_data, parameter) {
   # Check for empty data

R/get_session_code.R

@@ -4,7 +4,7 @@
 #' @param setts_obj The read settings object with all analysis specifications
 #' or the full session object from the App.
 #' @param output_path Path to write the resulting script file (e.g., "output_script.R")
-#' @return The output_path (invisibly)
+#' @returns The output_path (invisibly)
 #' @keywords internal
 #' @noRd
 get_code <- function(
@@ -80,7 +80,7 @@ get_code <- function(
 #' @param min_to_rep Minimum number of repeated elements to use `rep()` for
 #'   long vectors/lists.
 #' @param indent Integer indentation level for multi-line outputs.
-#' @return A single string containing R code that, when evaluated, will
+#' @returns A single string containing R code that, when evaluated, will
 #'   reconstruct `obj` (or a close approximation for complex types).
 #' @keywords internal
 clean_deparse <- function(obj, indent = 0, max_per_line = 10, min_to_rep = 3) {
@@ -207,7 +207,7 @@ clean_deparse.logical <- function(obj, indent = 0, max_per_line = 10, min_to_rep
 #'   the one installed from your aNCA package version.
 #' @param output_path Path to write the resulting script file.
 #'
-#' @return Invisibly returns the output_path.
+#' @returns Invisibly returns the output_path.
 #' @export
 get_settings_code <- function(
   settings_file_path,
@@ -249,7 +249,7 @@ get_settings_code <- function(
 #' @param output_path Path to write the resulting script file (e.g., "output_script.R").
 #' @param template_path Path to the R script template file. By default, uses the one
 #' installed from your aNCA package version.
-#' @return Invisibly returns the output_path.
+#' @returns Invisibly returns the output_path.
 #' @keywords Internal
 #' @noRd
 get_session_code <- function(

R/l_pkcl01.R

@@ -13,7 +13,8 @@
 #' @param subtitle A character string to parse specifying the subtitle to use for each list.
 #' @param footnote A character string to parse specifying the footnote of the listing table.
 #'
-#' @return A list of listings, each corresponding to a unique combination of the grouping variables.
+#' @returns A list of listings, each corresponding to a unique combination of
+#'   the grouping variables.
 #'
 #' @details
 #' The function performs the following steps:

R/label_operators.R

@@ -6,7 +6,7 @@
 #' @param labels_df A data frame containing at least the columns "Variable", "Label", and "Dataset".
 #' @param type The type variable in labels_df for which the labels are to be applied.
 #'
-#' @return The same dataset with label attributes applied to all columns.
+#' @returns The same dataset with label attributes applied to all columns.
 #' If a column is not present in the labels list, it will be assigned the name of the col.
 #' If label already exists in the original data, it will be preserved.
 #'
@@ -83,7 +83,7 @@ resolve_param_labels <- function(data) {
 #' @param type The type of the dataset for which the label is to be retrieved.
 #' @param labels_df A data frame containing at least the columns "Variable", "Label", and "Dataset".
 #'
-#' @return The label of the heading if it exists in the labels file,
+#' @returns The label of the heading if it exists in the labels file,
 #' otherwise the variable name.
 #'
 #' @examples
@@ -122,7 +122,7 @@ get_label <- function(variable, type = "ADNCA", labels_df = metadata_nca_variabl
 #' @param tooltip_vars A character vector of column names to include in the tooltip.
 #' @param type A character string specifying the label type for `get_label()`.
 #'
-#' @return A character vector of formatted HTML tooltip strings.
+#' @returns A character vector of formatted HTML tooltip strings.
 #'
 #' @examples
 #' # Sample data

R/pk_dose_qc_plot.R

@@ -31,7 +31,7 @@
 #'   `plotly` object.
 #' @param height Numeric. Desired height for the plot.
 #'
-#' @return A `ggplot` object or, if `as_plotly = TRUE`, a `plotly` object.
+#' @returns A `ggplot` object or, if `as_plotly = TRUE`, a `plotly` object.
 #'
 #' @export
 #' @importFrom ggplot2 ggplot aes geom_point facet_wrap scale_shape_manual
@@ -218,7 +218,7 @@ pk_dose_qc_plot <- function(data_conc,
 #' @param plot_conc_data Logical flag derived from `show_pk_samples` and `data_conc`.
 #' @param plot_dose_data Logical flag derived from `show_doses` and `data_dose`.
 #'
-#' @return A `list` containing `data` (the processed tibble), `shape_levels`,
+#' @returns A `list` containing `data` (the processed tibble), `shape_levels`,
 #'   and `colour_levels`.
 prepare_plot_data <- function(data_conc,
                               data_dose,
@@ -288,7 +288,7 @@ prepare_plot_data <- function(data_conc,
 #' Formats a unit string if a unique unit exists
 #' @param data The data frame to check.
 #' @param unit_var The column name of the unit variable.
-#' @return A formatted string like " (hr)" or an empty string "".
+#' @returns A formatted string like " (hr)" or an empty string "".
 format_unit_string <- function(data, unit_var) {
   # Return "" if the unit variable is not specified or doesn't exist
   if (is.null(unit_var) || !all(unit_var %in% names(data))) {

R/utils-plots.R

@@ -41,7 +41,7 @@
 #'
 #' @param msg Character string. The error message to display in the plot.
 #'
-#' @return A ggplot object with the error message displayed.
+#' @returns A ggplot object with the error message displayed.
 #' @keywords internal
 error_plot <- function(msg) {
   ggplot() +

R/utils-slope_selector.R

@@ -3,7 +3,7 @@
 #' Iterates over the given rules and updates the PKNCA object setting inclusion/exclusion flags.
 #' @param data PKNCA data object
 #' @param slopes Data frame of slope rules (TYPE, RANGE, REASON, group columns)
-#' @return Modified data object with updated flags
+#' @returns Modified data object with updated flags
 update_pknca_with_rules <- function(data, slopes) {
   slope_groups <- intersect(group_vars(data), names(slopes))
   time_col <- data$conc$columns$time