1.1 General guidelines and documentation workflow

Note that the ultimate goal of documentation is to have meaningful and consolidated help pages. For this reason, being happy about the roxygen tags in the source code is no enough, and the final help pages should always be checked as rendered by help(<TOPIC>).

To quickly iterate trough documentation development, updates and checks, the following is recommended.

• Use devtools::check_man(), which does some basic checks on top of roxygenizing your package, hinting about e.g. undocumented arguments.
• Assess the development version of the documentation via pkgload::dev_help(<TOPIC>), which is quicker than re-building the whole package and using help(), allowing faster iterations.
• The final documentation should be then checked using R CMD check (possibly with packages devtools or rcmdcheck), and the help pages assessed with help(<TOPIC>) after installing the package.
• For larger documentation efforts, it can be worth to generate the full PDF manual, where it is easier to also cross-check consistency at the whole package level.

An approach seen too often is to introduce roxygen documentation tags very early in the development of e.g. a function, using simple, pretty-uninformative placeholder tags. Early documentation is very useful if already thought-through upfront, to help thinking about and better design e.g. interfaces, usage, behavior, return values.

Early, poor documentation tags only serve the purpose of a skeleton, but may give the wrong impression of an actual documentation effort. Instead, it can be a good idea to add normal comments describing the function behavior (even a single comment saying what the function does). This can be the basis of proper, thought-through documentation tags at a more advanced development stage. Also note that RStudio offers the creation of a roxygen skeleton (Code > Insert Roxygen skeleton or Shift+Ctrl+Alt+), so there is little need / benefit in creating one manually, with poor content, ahead of time.