Advanced Documentation

Outline

  1. The duplication problem
  2. @inheritParams
  3. @inheritDotParams
  4. Markdown formatting
  5. Cross-references

The Duplication Problem

Two functions, overlapping parameters

cpue() and biomass_index() share catch, effort, and verbose.

cpue()

#' @param catch Numeric vector of
#'   catch (e.g., kg).
#' @param effort Numeric vector of
#'   effort (e.g., hours).
#' @param gear_factor Numeric scalar for gear 
#'   standardization (default 1)
#' @param method Character; 
#'   one of `"ratio"` (default) or `"log"`.
#' @param verbose Logical; Default from
#'   `getOption("fishr.verbose", FALSE)`.

biomass_index()

#' @param cpue Numeric vector of CPUE values. 
#' @param area_swept Numeric vector of area 
#'   swept (e.g., km^2^)
#' @param catch Numeric vector of
#'   catch (e.g., kg).
#' @param effort Numeric vector of
#'   effort (e.g., hours).
#' @param verbose Logical; Default from
#'   `getOption("fishr.verbose", FALSE)`.
#' @param ... Additional arguments 
#'   passed to `cpue()`.

Two problems:

  1. If the descriptions ever change, you have two places to update
  2. @param ... is vague - users cannot tell which arguments are accepted and passed to cpue()

@inheritParams

Copy parameter docs from another function

@inheritParams pulls @param entries from a source function into the current one.

#' Calculate Biomass Index
#'
#' @param cpue Numeric vector of CPUE values. If NULL, computed from `catch`
#'   and `effort`.
#' @param area_swept Numeric vector of area swept (e.g., km^2^).
#' @inheritParams cpue
#' @param ... Additional arguments passed to `cpue()`.
#' @export

Render documentation and open the help page:

document()
?biomass_index

What gets inherited?

roxygen2 copies @param entries from cpue() where the parameter:

  • appears in biomass_index()’s signature, and
  • is not already documented in biomass_index()
  • catch, effort, and verbose are inherited.
  • gear_factor and method are skipped - they are not explicit parameters of biomass_index().

@inheritParams also works across packages: @inheritParams pkg::function

@inheritDotParams

Make ... informative

@param ... tells users nothing.

#' @param ... Additional arguments passed to `cpue()`.

What are the additional arguments? What do they do?
The user has to go to the ?cpue() help and figure it out for themselves.

@inheritDotParams

generates a formatted description that names the forwarded arguments and links their documentation.

#' Calculate Biomass Index
#'
#' @param cpue Numeric vector of CPUE values. If NULL, computed from `catch`
#'   and `effort`.
#' @param area_swept Numeric vector of area swept (e.g., km^2^).
#' @inheritParams cpue
#' ... Additional arguments passed to `cpue()`.

@inheritDotParams

generates a formatted description that names the forwarded arguments and links their documentation.

#' Calculate Biomass Index
#'
#' @param cpue Numeric vector of CPUE values. If NULL, computed from `catch`
#'   and `effort`.
#' @param area_swept Numeric vector of area swept (e.g., km^2^).
#' @inheritParams cpue
#' @inheritDotParams cpue -catch -effort

The -catch -effort syntax excludes those parameters - they are already documented explicitly above.

What remains (gear_factor, method) is rendered as a formatted list linking back to ?cpue.

@inheritDotParams

The ... entry in the help page now reads something like:


... Arguments passed to cpue():
 gear_factor Numeric adjustment for gear standardisation…
 method One of “ratio” or “log”…

Markdown Formatting

Inline formatting

Standard Markdown works in all roxygen2 text fields: @param, @return, @description, @details.

#' @param area_swept Numeric vector of area swept in **km^2^**.
#' @return A numeric vector the same length as `cpue`. Returns `NA` for any
#'   row where either input is `NA`.
  • Backticks (``) render as inline code: cpue, NA, TRUE
  • **text** renders as bold
  • *text* renders as italic
  • ^text^ renders as superscript: km2

Lists

#' @details
#' Two modes of use:
#'
#' - Provide `cpue` directly for a simple calculation.
#' - Provide `catch` and `effort` to compute CPUE first, then scale by area.

The blank line between the tag and the list is required. Without it, roxygen2 treats the hyphens as literal text.

Cross-References

Linking to functions

The most common form: function name followed by () in square brackets [].

#' Calculates biomass index from CPUE and area swept.
#' See [cpue()] for computing CPUE values from raw catch and effort.

The () suffix tells roxygen2 this is a function link. It generates a code-formatted hyperlink to ?cpue.

Linking across packages

Use the :: operator inside the brackets:

#' @param data A data frame. See [dplyr::filter()] for subsetting rows.

This creates a link that opens ?dplyr::filter.

R CMD check may produce a NOTE: “Undeclared package ‘dplyr’ in Rd xrefs”. Adding the package to Suggests in your DESCRIPTION silences it - you do not need Imports.

Custom link text and @seealso

To display different text than the function name:

#' Returns the same structure as [the CPUE function][cpue()].

Use this sparingly - the function name itself is usually the most informative link text.

@seealso renders in its own section at the bottom of the help page:

#' @seealso [cpue()] to compute CPUE values from raw catch and effort.

Use it for functions that are related but not directly referenced in the body of the docs.

Summary

Syntax Result
[cpue()] Link to ?cpue in this package
[pkg::cpue()] Link to ?pkg::cpue in another package
[some text][cpue()] “some text” linking to ?cpue
@inheritParams cpue Copy matching @param entries from cpue()
@inheritDotParams cpue -x Document ... as forwarded args, excluding x

Use links freely in @description, @details, @param, @return, and @seealso. A well-linked help page lets users navigate the package without leaving the help system.