Advanced Documentation

The problem with duplicated documentation

Our biomass_index() function is in good shape after our testing sessions. Here is where we left it:

#' Calculate Biomass Index
#'
#' Calculates biomass index from CPUE and area swept. Can optionally
#' compute CPUE from catch and effort data.
#'
#' @param cpue Numeric vector of CPUE values. If `catch` and `effort` are
#'   provided, this is computed automatically.
#' @param area_swept Numeric vector of area swept (e.g., km^2^)
#' @param catch Optional numeric vector of catch. If provided with `effort`,
#'   CPUE is computed via `cpue()`.
#' @param effort Optional numeric vector of effort. Required if `catch` is
#'   provided.
#' @param verbose Logical; print processing info? Default from
#'   `getOption("fishr.verbose", FALSE)`.
#' @param ... Additional arguments passed to `cpue()` when computing from
#'   catch and effort (e.g., `method`, `gear_factor`).
#'
#' @return A numeric vector of biomass index values
#' @export
#'
#' @examples

And here is the documentation for cpue():

#' Calculate Catch Per Unit Effort (CPUE)
#'
#' Calculates CPUE from catch and effort data, with optional gear
#' standardization. Supports ratio and log-transformed methods.
#'
#' @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; print processing info? Default from
#'   `getOption("fishr.verbose", FALSE)`.
#'
#' @return A numeric vector of CPUE values
#' @export
#'
#' @examples

There are two documentation problems here:

catch and effort are already documented in cpue(). If the description of those parameters ever changes, we have two places to update.
The @param ... says “Additional arguments passed to cpue()” but gives the user no information about which arguments are accepted or what they do.

`@inheritParams`

@inheritParams copies parameter documentation from another function into the current one. You specify the source function, and roxygen2 copies the @param entries for any parameter whose name matches.

Replace the duplicated parameters with:

#' 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
biomass_index <- function(
  cpue = NULL,
  area_swept,
  catch = NULL,
  effort = NULL,
  verbose = getOption("fishr.verbose", FALSE),
  ...
) {
  # ...
}

roxygen2 looks at the @param tags in cpue() and copies documentation for any parameter that:

appears in the current function’s signature, and
is not already documented in the current function

document()

Open the help page to confirm:

?biomass_index

The duplicated parameter descriptions now match cpue() exactly - and they will stay in sync automatically whenever cpue() docs change.

Tip

@inheritParams can chain across functions. If function C inherits from B which inherits from A, roxygen2 resolves the full chain. It also works across packages: @inheritParams pkg::function.

`@inheritDotParams`

@param ... is vague. The user has to follow the cross-reference to cpue() and work out which arguments apply. @inheritDotParams generates a proper description that names the forwarded arguments and links their documentation automatically.

#' 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
#' @export
biomass_index <- function(
  cpue = NULL,
  area_swept,
  catch = NULL,
  effort = NULL,
  ...
) {
  # ...
}

The -catch -effort syntax excludes those parameters from the generated ... description, since they are already documented explicitly above. What remains - gear_factor, method, verbose - gets rendered as a formatted list linking back to ?cpue.

document()
?biomass_index

Users can see exactly what they can pass through without leaving the help page.

Markdown and cross-references

roxygen2 supports standard Markdown formatting in all text fields: @description, @details, @param, @return, @seealso, and others.

Inline formatting

The basics work as expected:

#' Calculate Biomass Index
#'
#' Calculates a biomass index by multiplying CPUE by area swept. Returns
#' `NA` for any row where either input is `NA`.
#'
#' @param cpue Numeric vector of CPUE values (units: kg/hr).
#' @param area_swept Numeric vector of area swept in **km^2^**.
#' @return A numeric vector the same length as `cpue`.

Backticks render as inline code: cpue, NA, TRUE
**text** renders as bold
*text* renders as italic

Lists

Use standard Markdown lists in @details or @description:

#' @details
#' Two modes of use:
#'
#' - Provide `cpue` directly for a simple calculation.
#' - Provide `catch` and `effort` to compute CPUE first, then scale by area.
#'
#' Any additional arguments in `...` are forwarded to [cpue()].

Blank lines between the tag and the list content are required - without them roxygen2 treats the hyphens as literal text.

Linking to functions

The most common form is the 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. This generates a code-formatted link that takes the user directly to ?cpue when they click it in the help document or a pkgdown site.

Linking across packages

To link to a function in another package, 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

To display different text than the function name, use the [text][target()] form:

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

This renders as “the CPUE function” with a link to ?cpue. Use this sparingly - the function name itself is usually the most informative link text.

The `@seealso` tag

#' @seealso [cpue()] to compute CPUE values from raw catch and effort.
#' @seealso [validate_numeric_inputs()] for the shared input validation logic.

@seealso renders in its own section at the bottom of the help page. 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
`[fishr::cpue()]`	Link to `?fishr::cpue` in another package
`[some text][cpue()]`	“some text” linking to `?cpue`

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.

The problem with duplicated documentation

@inheritParams

@inheritDotParams

Markdown and cross-references

Inline formatting

Lists

Linking to functions

Linking across packages

Custom link text

The @seealso tag

Summary

`@inheritParams`

`@inheritDotParams`

The `@seealso` tag