1.2 Content organization

Content structure and order of the roxygen2 documentation should be organized for readability, alignment with the rendered content, maintainability.

  • Apart from the @title (see below), always use sentence case with a final period (.).
  • Content order should reflect how sections appear in the resulting help page: title, description, arguments, details, value, custom sections, references, see also, examples.
    • Note that @family belongs to the ‘See Also’ section, so place it accordingly.
    • Place @inherit* and @template tags in the relevant place for the content you are including.
  • Use an empty line to separate sections
  • Avoid stating explicit @title and (single-paragraph) @description tags, they will be inferred by position.
  • Put single-paragraph content right after the tag (@details Bla bla.).
  • If you have multi-paragraph content for a single tag, separate the paragraphs with an empty line and start the first paragraph on a new line rather than right after the tag. Note that multi-paragraph description always requires an explicit @description.
  • Place NAMESPACE-related tags @importFrom, @import, @export at the bottom and in this order.
    • Use one @importFrom per symbol (not per package) and try to avoid @import.
    • For un-exported objects documented for internal purposes, specify @keywords internal instead of @export.
  • Use markdown: If not done at package level, @md should be the last element (so it can easily be removed when moving to package-level).
  • Do not use @rdname if not documenting multiple objects (see below).
  • Break lines at 80 characters of content (you can set Tools > Global Options > Code > Display > Margin column: 80 and > Show margin for visual aid): No matter how wide your screen is, human brain is still not meant for processing long text, which would be poorly readable (code is a different story).
    • Use RStudio menu Edit > Reflow comment (Shift+Ctrl+/) after selecting a single block (selecting several parts might screw things up), which will also indent the lines after the first when needed.

1.2.1 Note about @title

Keep in mind that the content of @title (the top paragraph, w/o explicit tag as recommended above) is used and displayed for two purposes in the R documentation:

  1. Title of the topics help page (the most know and natural usage).
  2. Brief description / hint to topics in the package help index (e.g. help(package = "roxygen2")), a less known and often forgotten usage.

With this in mind:

  • You may want to use title case (more natural for 1.) or sentence case (more sensible for 2.), but be consistent within a package (and never add a final period, ugly for 1.).
  • Avoid using the very same topic name as title (e.g. the function name when documenting a function). This does not provide any extra information, especially in the help index, where describing e.g. myFunction as “myFunction” is pretty pointless.