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:
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
:
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 @concept
s 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: