Reading Hadley's Package chapter about Documentation

Key point:

Use Roxygen comments in the R files - then the documentation takes care of itself!


Cut and pasted from: http://r-pkgs.had.co.nz/man.html

The documentation workflow

In this section, we’ll first go over a rough outline of the complete documentation workflow. Then, we’ll dive into each step individually. There are four basic steps:

1. Add roxygen comments to your .R files.
2. Run devtools::document() (or press Ctrl/Cmd + Shift + D in RStudio) to convert roxygen comments to .Rd files. (devtools::document() calls roxygen2::roxygenise() to do the hard work.)
3. Preview documentation with ?.
4. Rinse and repeat until the documentation looks the way you want.

Roxygen comments start with #'

For functions:

As well as the introduction block, most functions have three tags: @param, @examples and @return.

Introduction is the first part!

Each block includes some text before the first tag.1 This is called the introduction, and is parsed specially:

• The first sentence becomes the title of the documentation. That’s what you see when you look at help(package = mypackage) and is shown at the top of each help file. It should fit on one line, be written in sentence case, and end in a full stop.
• The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does.
• The third and subsequent paragraphs go into the details: this is a (often long) section that is shown after the argument description and should go into detail about how the function works.

All objects must have a title and description. Details are optional.

Well happy days (or evenings), I just completed my first documentation of a function!