Close #53.

Overview

This PR adds comprehensive roxygen2 documentation to all previously undocumented functions in the nhp_inputs R package. All utility functions, helper functions, and nested internal functions now have proper docstrings following roxygen2 conventions.

Changes

Added roxygen2 docstrings to 40+ functions across 18 files (~400 lines of documentation), including:

Core Utilities (R/ZZZ.R)

• Configuration and file path functions (params_path, params_filename, load_params)
• Data loading utilities (rtt_specialties, md_file_to_html)
• Security functions (encrypt_filename)
• Schema management (get_params_schema_text, create_params_schema)
• Environment detection (is_local)
• String utilities (sanitize_input_name)

Feature Functions (R/fct_*.R)

• Population visualization (age_pyramid)
• Configuration retrieval (get_population_growth_options)
• Value normalization (reduce_values and nested helper)

Golem Utilities (R/golem_utils_*.R)

• Reactive value helpers (rv, rvtl, drop_nulls)
• HTML manipulation (list_to_li, list_to_p, named_to_li, tag_remove_attributes, display, undisplay)

Module Utilities (R/mod_*_utils.R)

• Expatriation/repatriation visualizations (mod_expat_repat_trend_plot, mod_expat_repat_local_split_plot, mod_expat_repat_nonlocal_n, mod_expat_repat_nonlocal_icb_map)
• Table generation (mod_non_demographic_adjustment_table, mod_waiting_list_imbalances_table)

Model Run Functions (R/mod_run_model_*.R)

• API interaction (mod_run_model_submit, mod_run_model_check_container_status)
• Parameter processing (mod_run_model_fix_params, mod_run_model_remove_invalid_mitigators)
• Nested helpers (recursive_nullify, remove_item)

Visualization Functions

• Rate analysis plots (rates_boxplot, rates_trend_plot)

Nested Module Helpers

• UI generation (create_table, generate_param_controls)
• Data extraction (extract_expat_repat_data)
• Value conversion (get_default, convert_number)

Documentation Standards

All docstrings follow roxygen2 conventions and include:

• Clear titles: Brief one-line description of function purpose
• Detailed descriptions: Explanation of what the function does
• @param tags: Documentation for each parameter with type information
• @return tags: Description of return values
• @noRd tags: Marks internal functions not exported in package documentation

Example:

#' 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) {
  # ... function implementation
}

Impact

• No functional changes: Only documentation added; no code behavior modified
• Improved maintainability: All functions now have clear documentation
• Better developer experience: Easier to understand and maintain the codebase
• CI/CD ready: The existing GitHub Actions workflow will automatically generate .Rd files via devtools::document()

Testing

The existing CI workflow (.github/workflows/check.yaml) will:

1. Run devtools::document() to generate documentation files
2. Verify the repository is in a clean state after documentation generation
3. Fail if documentation is not up-to-date with source code

This ensures documentation stays synchronized with code changes going forward.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.