1.3 Advanced usage and consistent documentation
Several techniques and tools are available to enable and support a more consistent and maintainable documentation.
This can be described in detail in the Do repeat yourself section of vignette Generating Rd files, and are summarized as follows
- Cross-link documentation files with
- Reuse parameter documentation with
- Document multiple functions in the same place with
- Run arbitrary R code with
- Create reusable templates with
1.3.1 Roxygen templates and example scripts
Roxygen templates allow modularizing documentation content. Shared content
sits in R files under the man-roxygen directory, and is included using the
Similarly, examples written as normal R code can be included in the ‘Examples’
s), which for long examples is way more
convenient and less tedious than writing them as roxygen comments in the
- The man-roxygen directory must be added to .Rbuildignore, e.g. via
- Template files should be called
<TAG>-<NAME>.Rdepending on which
@<TAG>they contain (typically one per template), and be included according to the corresponding tag order. This improves the readability and maintenance of template-based documentation
#' @param first_arg Bla bla bla.
- Markdown must be specified via
@mdin each template if not defined at package level.
- Examples R scripts should be called
ex-<FUNCTION_NAME>.Rand placed in man-roxygen (for convenience). They are then included via
@describeIn are a convenient way to document multiple
functions in the same file. See the roxygen2 vignette Generating Rd
vignette("rd", package = "roxygen2")) for more detail.
In both case, not that
@title should be specified only for the main
documentation object, since it will be ignored for others (a help page allowing
only one title).
It may also be convenient to collect the main generic documentation content as
roxygen2 tags for a
NULL object with an explicit
@name (see examples below).
@rdname provides the greatest flexibility for combining documentation
(description, arguments, details, etc.) of several objects into a single
@rdname should the first tag, and should be used exclusively when
appending documentation content for a new object to another existing
@rdname. Having an
@rdname for single and full-documented objects should be
- it is redundant and unnecessary;
- it gives the impression we want to document this object alongside others;
- it does not help if we later want to change the
@rdnameto a different topic, since the documentation content must be probably adapted (e.g.
@titleshould be removed as it would be ignored).
@describeIn <name> <description> is meant for a set of functions with
(almost) same arguments and that can be described in a general way in the
‘Description’ section, whereas individual
<description>s are collected in a
final section ‘Functions’.
@describeIn should be the last tag before the specific
namespace tags (and possibly after specific