Document package functions. Use when asked to document functions.
All functions should be documented in {roxygen2} #' style, including internal/unexported functions.
air format . then devtools::document() after changing any roxygen2 docs.Parameters used in more than one function should be documented in R/aaa-shared.R under the @name shared-params section. Functions then use @inheritParams shared-params to inherit these parameter definitions.
The aaa-shared.R file:
@name shared-params to group all parameters under one documentation topic@keywords internal to mark it as internalNULL (required for roxygen2 processing)#' @param paramName (`TYPE`) One sentence description. Can include [cross_references()].
#' Additional details on continuation lines if needed.
Function-specific @param definitions always appear before any @inheritParams lines.
character)" - Character vectorlength-1 character)" - Single stringlength-1 integer)" - Single integerlength-1 logical)" - Single booleandata.frame)" - Data framelist)" - List objectenvironment)" - Environment objectWhen a parameter takes one of a fixed set of values, document them with a bullet list:
#' @param strState (`length-1 character`) State of issues to fetch. Can be
#' one of:
#' * `"open"`: Open issues only.
#' * `"closed"`: Closed issues only.
#' * `"all"`: All issues regardless of state.
#' Title in sentence case
#'
#' Description paragraph providing context and details.
#'
#' @param strParam (`TYPE`) Description.
#' @inheritParams shared-params
#'
#' @returns Description of return value.
#' @seealso [RelatedFunction()]
#' @export
#'
#' @examples
#' ExampleFunction()
#' lines separate: title/description, description/params, and @export/@examples.@seealso (optional) goes between @returns and @export.@details can supplement the description when needed.Use @returns (not @return) with specific details:
Simple returns:
#' @returns An integer representing the number of unique non-NA values.
Structured returns with columns:
#' @returns A `qcthat_Issues` object, which is a [tibble::tibble()] with
#' columns:
#' - `Issue`: Issue number.
#' - `Title`: Issue title.
#' - `State`: Issue state (`open` or `closed`).
Invisible returns:
#' @returns The input `chrChecks`, invisibly.
#' @returns `NULL` (invisibly).
Use square brackets for function cross-references:
[tibble::tibble()], [glue::glue()][FetchRepoIssues()], [CompileTestResults()]These auto-generate hyperlinks in help documentation.
For interactive/network-dependent functions:
#' @examplesIf interactive()
#'
#' FetchRepoIssues()
For self-contained examples:
#' @examples
#' CompileTestResults(test_results_object)
The @examplesIf interactive() pattern skips examples during R CMD check.
Use @rdname to group related functions (especially S3 methods) under one help page:
#' Printing qcthat objects
#' @name printing
NULL
#' @rdname printing
#' @export
print.qcthat_Object <- function(x, ...) { ... }
#' @rdname printing
#' @export
format.qcthat_Object <- function(...) { ... }
For S3 methods of functions from other packages:
#' @exportS3Method dplyr::filter
filter.qcthat_IssueTestMatrix <- function(.data, ...) { ... }
Internal (unexported) functions use abbreviated documentation:
#' Title in sentence case
#'
#' @inheritParams shared-params
#' @returns Use the rules as described above.
#' @keywords internal
@description paragraph after the title.#' lines between sections (other than the title and the rest).@keywords internal instead of @export.@examples nor @examplesIf.