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 @seealso and @family.
  • Reuse parameter documentation with @inherit, @inheritParams, and @inheritSections.
  • Document multiple functions in the same place with @describeIn or @rdname.
  • Run arbitrary R code with @eval.
  • Create reusable templates with @template and @templateVar.

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 @template tag.

Similarly, examples written as normal R code can be included in the ‘Examples’ section using @example (without s), which for long examples is way more convenient and less tedious than writing them as roxygen comments in the @examples section.

  • The man-roxygen directory must be added to .Rbuildignore, e.g. via usethis::use_build_ignore("man-roxygen")
  • Template files should be called <TAG>-<NAME>.R depending 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
    • e.g., param-first_arg.R contains #' @param first_arg Bla bla bla.
  • Markdown must be specified via @md in each template if not defined at package level.
  • Examples R scripts should be called ex-<FUNCTION_NAME>.R and placed in man-roxygen (for convenience). They are then included via @example man-roxygen/ex-<FUNCTION_NAME>.R.

1.3.2 Using @rdname and @describeIn

Tags @rdname and @describeIn are a convenient way to document multiple functions in the same file. See the roxygen2 vignette Generating Rd files (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).

Usage of @rdname

@rdname provides the greatest flexibility for combining documentation (description, arguments, details, etc.) of several objects into a single documentation entry.

Tag @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 avoided since

  • 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 @rdname to a different topic, since the documentation content must be probably adapted (e.g. @title should be removed as it would be ignored).

Usage of @describeIn

@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’.

Tag @describeIn should be the last tag before the specific @examples and namespace tags (and possibly after specific @param).