Indexing and cross-references

In roxygen2: In-Line Documentation for R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

This vignette discusses tags that help users finding documentation through cross-references and indexes.

See also

@seealso allows you to point to other useful resources, either on the web (using a url) or to related functions (with a function link like [function_name()]). For sum(), this might look like:

#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and
#'   [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.

Family

If you have a family of related functions, you can use @family {family} to cross-reference each function to every member of the family. A function can be a member of multiple families.

By default @family {family}, will generate the see also text "Other {family}:", so the @family name should be plural (i.e., "model building helpers" not "model building helper").

If you want to override the default title, you can provide an rd_family_title element in a list stored in man/roxygen/meta.R:

list(
  rd_family_title = list(aggregations = "Aggregation functions")
)

References

If the object you're documenting has connections to the scientific literature, use @reference to provide a citation.

Aliases

? and help() look for topic aliases; ?foo will find any topic that contains the foo alias.

roxygen2 generates a default alias for you based on the object you're documenting. You can add additional aliases with @aliases alias1 alias2 alias3 or remove default alias with @aliases NULL.

Search

As well as looking in the aliases, help.search() and ??? also look in the @title, @keywords, and @concepts tags.

• @keywords adds standard keywords, which must be present in file.path(R.home("doc"), "KEYWORDS").

• @concept adds arbitrary key words or phrases. Each @concept should contain a single word or phrase.

Generally speaking, @keywords and @concepts are not terribly useful because most people find documentation using Google, not R's built-in search.

There's one exception: @keywords internal. It's useful because it removes the function from the documentation index; it's useful for functions aimed primarily at other developers, not typical users of the package.

Back references

The original source location is added as a comment to the second line of each generated .Rd file in the following form:

% Please edit documentation in ...

roxygen2 tries to capture all locations from which the documentation is assembled. For code that generates R code with Roxygen comments (e.g., the Rcpp package), the @backref tag is provided. This allows specifying the "true" source of the documentation, and will substitute the default list of source files. Use one tag per source file:

#' @backref src/file.cpp
#' @backref src/file.h

roxygen2 documentation built on June 28, 2024, 9:11 a.m.