Add comprehensive roxygen2 docstrings to all R package functions

R/ZZZ.R

@@ -9,11 +9,26 @@ utils::globalVariables(c(
   ".env"
 ))
 
+#' Get RTT specialties data
+#'
+#' Reads the RTT specialties CSV file from the app data directory.
+#'
+#' @return A tibble containing RTT specialty codes and names.
+#' @noRd
 rtt_specialties <- function() {
   app_sys("app", "data", "rtt_specialties.csv") |>
     readr::read_csv(col_types = "cc")
 }
 
+#' Sanitize input names
+#'
+#' Converts input names to a standardized format by converting to lowercase,
+#' replacing whitespace/underscores with hyphens, and removing invalid characters.
+#'
+#' @param .x A character vector of input names to sanitize.
+#'
+#' @return A character vector of sanitized input names.
+#' @noRd
 sanitize_input_name <- function(.x) {
   .x |>
     stringr::str_to_lower() |>
@@ -27,6 +42,16 @@ if (FALSE) {
   .env <- NULL
 }
 
+#' Convert markdown file to HTML
+#'
+#' Reads a markdown file from the app directory and converts it to HTML.
+#'
+#' @param ... Character vectors specifying subdirectory and file(s) within the
+#'   app package. Passed to \code{app_sys()}.
+#'
+#' @return An HTML object containing the rendered markdown, or NULL if the file
+#'   doesn't exist.
+#' @noRd
 md_file_to_html <- function(...) {
   file <- app_sys(...)
 
@@ -37,6 +62,15 @@ md_file_to_html <- function(...) {
   shiny::HTML(markdown::mark_html(file, output = FALSE, template = FALSE))
 }
 
+#' Load parameters from JSON file
+#'
+#' Reads model parameters from a JSON file and handles backward compatibility
+#' for old parameter structures.
+#'
+#' @param file Path to the JSON file containing parameters.
+#'
+#' @return A list containing the model parameters.
+#' @noRd
 load_params <- function(file) {
   p <- jsonlite::read_json(file, simplifyVector = TRUE)
 
@@ -52,6 +86,16 @@ load_params <- function(file) {
   p
 }
 
+#' Get parameters directory path
+#'
+#' Constructs the file path to the parameters directory for a given user and
+#' dataset, creating the directory if it doesn't exist.
+#'
+#' @param user Username or NULL for default.
+#' @param dataset Dataset identifier.
+#'
+#' @return Character string containing the path to the parameters directory.
+#' @noRd
 params_path <- function(user, dataset) {
   path <- file.path(
     get_golem_config("params_data_path"),
@@ -65,18 +109,45 @@ params_path <- function(user, dataset) {
   path
 }
 
+#' Get parameters filename
+#'
+#' Constructs the full file path for a scenario parameters file.
+#'
+#' @param user Username or NULL for default.
+#' @param dataset Dataset identifier.
+#' @param scenario Scenario name.
+#'
+#' @return Character string containing the full path to the parameters file.
+#' @noRd
 params_filename <- function(user, dataset, scenario) {
   file.path(
     params_path(user, dataset),
     paste0(scenario, ".json")
   )
 }
 
-# check to see whether the app is running locally or in production
+#' Check if app is running locally
+#'
+#' Determines whether the app is running in a local development environment
+#' or in production based on environment variables.
+#'
+#' @return Logical indicating if the app is running locally (TRUE) or in
+#'   production (FALSE).
+#' @noRd
 is_local <- function() {
   Sys.getenv("SHINY_PORT") == "" || !getOption("golem.app.prod", TRUE)
 }
 
+#' Encrypt a filename
+#'
+#' Encrypts a filename using AES-CBC encryption with HMAC for integrity.
+#'
+#' @param filename Character string containing the filename to encrypt.
+#' @param key_b64 Base64-encoded encryption key. Defaults to the
+#'   NHP_ENCRYPT_KEY environment variable.
+#'
+#' @return Base64-encoded string containing the encrypted filename with HMAC.
+#' @noRd
 encrypt_filename <- function(
   filename,
   key_b64 = Sys.getenv("NHP_ENCRYPT_KEY")
@@ -91,6 +162,16 @@ encrypt_filename <- function(
   openssl::base64_encode(c(hm, ct))
 }
 
+#' Get parameters schema text
+#'
+#' Downloads and reads the JSON schema for model parameters from the GitHub
+#' Pages site.
+#'
+#' @param app_version Version of the app to get the schema for. Defaults to the
+#'   INPUTS_DATA_VERSION environment variable or "dev" if not set.
+#'
+#' @return Character string containing the JSON schema text.
+#' @noRd
 get_params_schema_text <- function(
   app_version = Sys.getenv("INPUTS_DATA_VERSION", "dev")
 ) {
@@ -109,6 +190,14 @@ get_params_schema_text <- function(
   paste(readLines(tf), collapse = "\n")
 }
 
+#' Create parameters schema object
+#'
+#' Creates a JSON schema validator object from schema text.
+#'
+#' @param schema_text Character string containing the JSON schema definition.
+#'
+#' @return A jsonvalidate json_schema object.
+#' @noRd
 create_params_schema <- function(schema_text) {
   jsonvalidate::json_schema$new(schema_text)
 }

R/fct_age_pyramid.R

@@ -1,3 +1,12 @@
+#' Create an age pyramid plot
+#'
+#' Generates a population pyramid visualization showing age and sex distribution.
+#'
+#' @param age_data A data frame containing age group, sex, and population count data.
+#'   Expected columns: age_group, sex (1=Males, 2=Females), and n (count).
+#'
+#' @return A ggplot2 object representing the age pyramid.
+#' @noRd
 age_pyramid <- function(age_data) {
   age_data |>
     dplyr::mutate(

R/fct_population_growth.R

@@ -1,3 +1,12 @@
+#' Get population growth options
+#'
+#' Retrieves the available population growth projection options for a given dataset
+#' from the golem configuration.
+#'
+#' @param dataset Dataset identifier used to retrieve dataset-specific configuration.
+#'
+#' @return A named list of population growth projection values.
+#' @noRd
 get_population_growth_options <- function(dataset) {
   projections <- get_golem_config(
     "population_projections",

R/golem_utils_ui.R

@@ -151,7 +151,7 @@ undisplay <- function(tag) {
   # if not already hidden
   if (
     !is.null(tag$attribs$style) &&
-      !grepl("display:\\s+none", tag$attribs$style)
+      !grepl("display:\\s+none", tag$attribs$style) # fmt: skip
   ) {
     tag$attribs$style <- paste(
       "display: none;",
@@ -167,7 +167,7 @@ undisplay <- function(tag) {
 display <- function(tag) {
   if (
     !is.null(tag$attribs$style) &&
-      grepl("display:\\s+none", tag$attribs$style)
+      grepl("display:\\s+none", tag$attribs$style) # fmt: skip
   ) {
     tag$attribs$style <- gsub(
       "(\\s)*display:(\\s)*none(\\s)*(;)*(\\s)*",

R/mod_baseline_adjustment_ui.R

@@ -4,15 +4,26 @@
 #'
 #' @param id,input,output,session Internal parameters for {shiny}.
 #'
-#' @noRd
-#'
 #' @importFrom shiny NS tagList
+#'
+#' @noRd
 mod_baseline_adjustment_ui <- function(id) {
   ns <- shiny::NS(id)
 
   specs <- rtt_specialties() |>
     dplyr::mutate(sanitized_code = sanitize_input_name(.data[["code"]]))
 
+  # Create baseline adjustment table UI
+  #
+  # Internal helper function to create a gt table with baseline values,
+  # adjustment sliders, and computed parameters for different specialties.
+  #
+  # @param at Activity type (e.g., "ip", "op", "aae").
+  # @param g Group identifier (e.g., "elective", "non-elective").
+  # @param df Data frame containing specialty information (default: specs).
+  #
+  # @return A gt table object with baseline adjustment controls.
+  # @noRd
   create_table <- function(at, g, df = specs) {
     df |>
       dplyr::mutate(

R/mod_expat_repat_server.R

@@ -32,6 +32,15 @@ mod_expat_repat_server <- function(
 
     # helpers ----
 
+    # Extract expatriation/repatriation data
+    #
+    # Internal helper function to filter expatriation/repatriation data based
+    # on selected activity type, subgroup, and specialty/type.
+    #
+    # @param dat Data frame containing expatriation/repatriation data.
+    #
+    # @return Filtered data frame based on input selections.
+    # @noRd
     extract_expat_repat_data <- function(dat) {
       # TODO: techdebt
       # we should rename the dropdowns

R/mod_expat_repat_ui.R

@@ -4,12 +4,24 @@
 #'
 #' @param id,input,output,session Internal parameters for {shiny}.
 #'
-#' @noRd
-#'
 #' @importFrom shiny NS tagList
+#'
+#' @noRd
 mod_expat_repat_ui <- function(id) {
   ns <- shiny::NS(id)
 
+  # Generate parameter controls
+  #
+  # Internal helper function to create UI controls for expatriation/repatriation
+  # parameters including a checkbox and slider.
+  #
+  # @param type Parameter type identifier (e.g., "expat", "repat_local").
+  # @param min Minimum value for the slider.
+  # @param max Maximum value for the slider.
+  # @param values Initial values for the slider range.
+  #
+  # @return A shiny fluidRow containing the parameter controls.
+  # @noRd
   generate_param_controls <- function(type, min, max, values) {
     shiny::fluidRow(
       col_3(

R/mod_expat_repat_utils.R

@@ -1,3 +1,17 @@
+#' Create expatriation/repatriation trend plot
+#'
+#' Generates a line plot showing trends in expatriation or repatriation rates
+#' over time with an optional prediction interval.
+#'
+#' @param df A data frame containing financial year (fyear) and percentage (pcnt) data.
+#' @param include Logical indicating whether to include the prediction interval.
+#' @param values Numeric vector of length 2 with lower and upper prediction interval bounds.
+#' @param start_year The baseline financial year to highlight.
+#' @param title Title for the y-axis.
+#' @param scale Scaling factor for determining y-axis limits (default: 10).
+#'
+#' @return A ggplot2 object representing the trend plot.
+#' @noRd
 mod_expat_repat_trend_plot <- function(
   df,
   include,
@@ -53,6 +67,18 @@ mod_expat_repat_trend_plot <- function(
     )
 }
 
+#' Create local provider split visualization
+#'
+#' Generates a stacked bar chart showing the distribution of activity across
+#' different local providers.
+#'
+#' @param df A data frame containing provider and count data.
+#' @param providers Named vector mapping provider names to codes.
+#' @param dataset The current dataset/provider identifier.
+#' @param start_year The financial year for the data.
+#'
+#' @return A ggplot2 object representing the provider split.
+#' @noRd
 mod_expat_repat_local_split_plot <- function(
   df,
   providers,
@@ -113,6 +139,15 @@ mod_expat_repat_local_split_plot <- function(
     ggplot2::theme(legend.position = "none")
 }
 
+#' Create non-local activity volume plot
+#'
+#' Generates a bar chart showing the number of spells delivered to non-local
+#' ICB residents over time.
+#'
+#' @param df A data frame containing financial year (fyear) and count (n) data.
+#'
+#' @return A ggplot2 object representing the volume plot.
+#' @noRd
 mod_expat_repat_nonlocal_n <- function(df) {
   df |>
     ggplot2::ggplot(
@@ -144,6 +179,15 @@ mod_expat_repat_nonlocal_n <- function(df) {
 }
 
 
+#' Create non-local ICB geographic map
+#'
+#' Generates an interactive leaflet map showing the geographic distribution
+#' of non-local ICB activity.
+#'
+#' @param df A spatial data frame containing ICB boundaries and activity percentages.
+#'
+#' @return A leaflet map object.
+#' @noRd
 mod_expat_repat_nonlocal_icb_map <- function(df) {
   # nolint start: object_usage_linter
   pal <- leaflet::colorNumeric(

R/mod_mitigators_rates_boxplot.R

@@ -1,3 +1,15 @@
+#' Create a boxplot of rates data
+#'
+#' Generates a boxplot visualization with beeswarm points showing the
+#' distribution of rates data.
+#'
+#' @param trend_data A data frame containing rate data with columns for rate
+#'   and is_peer indicator.
+#' @param plot_range Numeric vector of length 2 specifying y-axis limits.
+#' @param interval ggplot2 layer to add interval visualization.
+#'
+#' @return A ggplot2 object representing the rates boxplot.
+#' @noRd
 rates_boxplot <- function(trend_data, plot_range, interval) {
   trend_data |>
     ggplot2::ggplot(ggplot2::aes(x = "", y = .data$rate)) +