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
@familybelongs to the ‘See Also’ section, so place it accordingly.
@templatetags in the relevant place for the content you are including.
- Note that
- Use an empty line to separate sections
- Avoid stating explicit
@descriptiontags, 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
- Place NAMESPACE-related tags
@exportat the bottom and in this order.
- Use one
@importFromper symbol (not per package) and try to avoid
- For un-exported objects documented for internal purposes, specify
@keywords internalinstead of
- Use one
If not done at package level,
@mdshould be the last element (so it can easily be removed when moving to package-level).
- Do not use
@rdnameif 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
- 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
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
- Title of the topics help page (the most know and natural usage).
- 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.
myFunctionas “myFunction” is pretty pointless.