This vignette discusses tags that help users finding documentation through cross-references and indexes.
@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.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 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")
)If the object you’re documenting has connections to the scientific
literature, use @reference to provide a citation.
? 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.
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.
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