roxygen2-documentation

# roxygen2 Documentation ## Overview roxygen2 allows you to write documentation directly above your R code using special comments starting with `#'`. This skill covers all essential roxygen2 tags, Markdown formatting, and documentation patterns. ## Core Concepts ### Basic Structure ```r #' Function title (one line, sentence case) #' #' Longer description paragraph providing more details about what #' the function does, when to use it, and any important context. #' #' @param x Description of parameter x #' @param y Description of parameter y #' @returns Description of return value #' @export #' @examples #' my_function(1, 2) my_function <- function(x, y) { # implementation } ``` **Required components:** 1. Title (first line, no blank line before it) 2. Blank line (separates title from description) 3. Description (optional but recommended) 4. Blank line (separates description from tags) 5. Tags (@param, @returns, @export, etc.) ### Generating Documentation ```r # Generate .Rd files and NAMESPACE: devtools::document() # Or: roxygen2::roxygenise() # Preview documentation: ?my_function ``` ## Essential Tags ### @param Documents function parameters. One @param per parameter. ```r #' @param x A numeric vector of values #' @param y A numeric vector, same length as x #' @param method Character string specifying the method to use. #' Options are "mean" (default), "median", or "mode". #' @param verbose Logical. If TRUE, prints progress messages. #' Default is FALSE. #' @param ... Additional arguments passed to underlying functions ``` **Patterns:** - Start with type description ("A numeric vector", "Character string") - Explain constraints (length, range, allowed values) - Document defaults if not obvious - Use `...` for dots ### @returns (Preferred) / @return Documents what the function returns. Use `@returns` (plural) in new code. ```r #' @returns A numeric vector of the same length as the input my_function <- function(x) { x * 2 } #' @returns A data frame with columns: #' \describe{ #' \item{id}{Character. Unique identifier} #' \item{value}{Numeric. Measured value} #' \item{timestamp}{POSIXct. Time of measurement} #' } my_summarize <- function(data) { # ... } #' @returns Invisible NULL. Called for side effects (prints plot). my_plot <- function(x) { plot(x) invisible(NULL) } #' @returns A list with components: #' * `estimate`: Numeric vector of estimates #' * `std_error`: Standard errors #' * `p_value`: P-values my_test <- function(x, y) { list( estimate = c(1, 2), std_error = c(0.1, 0.2), p_value = c(0.01, 0.05) ) } ``` **Note**: `@return` (singular) is older but still works. `@returns` is now preferred. ### @export Marks function for export (makes it available to users). ```r #' User-facing function #' @export public_function <- function() { # ... } #' Internal function (no @export) internal_helper <- function() { # ... } ``` **When to export:** - Functions users should call directly - S3 methods for generics from other packages (often) - Datasets (automatically exported from data/) **When NOT to export:** - Internal helper functions - Functions only called by other package functions - S3 methods for your own generics (use @export with method) ### @examples Provides executable examples. ```r #' @examples #' # Basic usage #' result <- my_function(1:10) #' #' # With different parameters #' result2 <- my_function(1:10, method = "median") #' #' # Handling edge cases #' my_function(numeric(0)) # Empty input my_function <- function(x, method = "mean") { # ... } ``` **Best practices:** - Include comments explaining what each example shows - Show basic usage first, then advanced - Demonstrate important edge cases - Keep examples short and focused - Examples are run by R CMD check! ### @examplesIf Conditionally run examples (new in roxygen2 7.2.0). ```r #' @examplesIf requireNamespace("ggplot2", quietly = TRUE) #' library(ggplot2) #' ggplot(data, aes(x, y)) + geom_point() #' @examplesIf interactive() #' # Only run in interactive sessions #' my_interactive_function() #' @examplesIf identical(Sys.getenv("NOT_CRAN"), "true") #' # Only on GitHub Actions, not CRAN #' slow_test() ``` ### \dontrun{} vs \donttest{} Control example execution during R CMD check. ```r #' @examples #' # This runs: #' my_function(1:10) #' #' \dontrun{ #' # This is shown but NEVER run (not even by check): #' # Use for code that requires user interaction or credentials #' my_function(get_user_input()) #' set_api_key("your-key-here") #' } #' #' \donttest{ #' # This is run by check, but not by example(): #' # Use for slow operations #' very_slow_operation() #' } ``` **Guidelines:** - Prefer runnable examples when possible - Use `\dontrun{}` for interactive code, credentials, web APIs - Use `\donttest{}` for slow operations (>5 seconds) - Use `@examplesIf` instead when appropriate ### @importFrom Imports specific functions from other packages into your namespace. ```r #' @importFrom dplyr filter mutate select #' @importFrom rlang .data %||% #' @importFrom stats median sd NULL ``` **Placement:** - Package-level documentation file (R/mypackage-package.R) - Or in individual function documentation - Or in a dedicated R/aaa-imports.R file ```r # R/aaa-imports.R #' @importFrom dplyr filter mutate select arrange #' @importFrom rlang .data .env %||% !! !!! #' @importFrom magrittr %>% NULL ``` ### @import Imports entire package namespace (rarely recommended). ```r #' @import rlang NULL ``` **Only use for:** - rlang (if building tidyverse-style package) - Your own internal utilities package **Avoid for:** - Most packages (use @importFrom or pkg::fun() instead) - Risk of namespace conflicts ### @keywords internal Marks function as internal (hides from package index). ```r #' Internal helper function #' #' This function is not intended for direct use. #' #' @keywords internal #' @export internal_but_exported <- function() { # Sometimes needed for S3 methods, package architecture } ``` **Use when:** - Function must be exported (e.g., S3 method) but isn't user-facing - Internal APIs for advanced users ## Inheritance and Linking ### @inheritParams Inherits parameter documentation from another function. ```r #' Base function #' @param x A numeric vector #' @param y A numeric vector #' @param method Method to use: "mean", "median", or "mode" base_function <- function(x, y, method = "mean") { # ... } #' Wrapper function #' @inheritParams base_function #' @param z Additional parameter wrapper_function <- function(x, y, method = "mean", z) { base_function(x, y, method) # ... use z ... } ``` **Benefits:** - Reduces duplication - Ensures consistency - Easier maintenance ### @inherit Inherits various documentation sections. ```r #' Original function #' @param x Input #' @returns Output #' @examples #' original(1:10) original <- function(x) { # ... } #' @inherit original examples #' @inheritParams original #' @returns Modified output modified <- function(x) { # different implementation } ``` **Can inherit:** - `@inherit fun params` - all parameters - `@inherit fun return` - return value - `@inherit fun examples` - examples - `@inherit fun description` - description - `@inherit fun details` - details - `@inherit fun` - everything ### @family Creates "See Also" links to related functions. ```r #' @family statistical functions mean_wrapper <- function(x) { mean(x) } #' @family statistical functions median_wrapper <- function(x) { median(x) } #' @family statistical functions mode_wrapper <- function(x) { # ... } ``` Generates links: "Other statistical functions: median_wrapper(), mode_wrapper()" ### @seealso Manual cross-references and external links. ```r #' @seealso [related_function()] for related functionality #' @seealso [other_package::their_function()] for alternative approach #' @seealso <https://example.com> for more details #' @seealso `vignette("introduction")` for tutorial ``` ### @rdname Combines documentation of multiple functions on one page. ```r #' Get or set configuration #' #' @param key Configuration key #' @param value Configuration value #' @rdname config #' @export get_config <- function(key) { pkg_env$config[[key]] } #' @rdname config #' @export set_config <- function(key, value) { pkg_env$config[[key]] <- value invisible(value) } ``` **Generates single help page:** `?config` shows both functions. **Use for:** - Getter/setter pairs - Function families that are always used together - Different interfaces to same functionality ### @describeIn Documents multiple related items with individual descriptions. ```r #' Process data #' #' @param x Input data #' @export process <- function(x) { UseMethod("process") } #' @describeIn process Process numeric vectors #' @export process.numeric <- function(x) { # ... } #' @describeIn process Process character vectors #' @export process.character <- function(x) { # ... } #' @describeIn process Process data frames #' @export process.data.frame <- function(x) { # ... } ``` **Generates:** Single page with subsections for each method. ## Markdown Support Enable in DESCRIPTION: ```dcf Roxygen: list(markdown = TRUE) ``` ### Text Formatting ```r #' Function with *italic*, **bold**, and `code` text #' #' You can use _italic_ and __bold__ alternatives too. #' #' Inline code: `x + y` #' #' Code blocks: #' ``` #' result <- my_function( #' x = 1:10, #' method = "mean" #' ) #' ``` ``` ### Lists ```r #' Bulleted list: #' * Item 1 #' * Item 2 #' * Nested item #' * Item 3 #' #' Numbered list: #' 1. First step #' 2. Second step #' 3. Third step #' #' Definition list: #' * `term1`: Definition of term 1 #' * `term2`: Definition of term 2 ``` ### Links ```r #' See [my_function()] for details #' #' See [other_package::their_function()] for alternatives #'