Chapter 5 Documenting

Each function in R package must contain a help topic. R package roxygen2 lets write some special comments at the start of each function which will be used to create documentation.

To insert a documentation skeleton in RStudio click inside a function, then open the Code menu and select Insert Roxygen skeleton or use Ctrl + Alt + Shift + R. The inserted code looks like this:

#' Title
#'
#' @param x 
#' @param na.rm 
#'
#' @return
#' @export
#'
#' @examples

5.1 Building documentation

Now we can build our documentation using the document() function from the devtools package.

devtools::document()
ℹ Updating myutils documentation
First time using roxygen2. Upgrading automatically...
Updating roxygen version in /projectnb2/krcs/rpackage/myutils/DESCRIPTION
ℹ Loading myutils
Warning: The existing 'NAMESPACE' file was not generated by roxygen2, and will not be overwritten.
Writing numeric_summary.Rd
Writing char_summary.Rd

We can see from the output that this operation made a few changes to our project:

First it updated the DESCRIPTION file. It added the following line: RoxygenNote: 7.1.2 at the bottom of the file.

Then it updated the NAMESPACE file. If you received a warning that the existing NAMESPACE file was not generated by roxygen2 then delete your current version and run document() function again:

> devtools::document()
ℹ Updating myutils documentation
ℹ Loading myutils
Writing NAMESPACE
Writing NAMESPACE

NAMESPACE now contains the following two line (one line per each function we documented):

# Generated by roxygen2: do not edit by hand

export(char_summary)
export(numeric_summary)

We can also see two Rd files in the man/ sub-directory. These files will be converted to the help-topics when the package is installed.

5.2 Checking documentation

Type ?numeric_summary in the Console window to see the help topic for the numeric_summary. Check if everything is correct. Then check help topic for the char_summary() function.

We can see that we can add some additional formatting. For example, we can mark blocks of code with \code{}

5.3 Check and save current version

Finally it’s a good practice to check the package again, load the current version, and make a commit:

> check()
ℹ Updating myutils documentation
ℹ Loading myutils
Writing NAMESPACE
Writing NAMESPACE
── Building ────────

. . .

── R CMD check results ──────────────────────────────────────────────────────────────── myutils 0.1.1 ────
Duration: 13.1s

0 errors ✓ | 0 warnings ✓ | 0 notes ✓

We should see no errors, warnings or notes.

> load_all()

5.4 Formatting documentation

  • \emph{italics}: italics
  • \strong{bold}: bold
  • \code{myutil}: formatted inline code
  • \preformatted{}: format text as is for multiline code
  • \url{http://rstudio.com}: a url
  • \href{http://rstudio.com}{Rstudio}: a url with custom link text
  • \email{hadley@@rstudio.com} (note the doubled @): an email address

For a numbered, bulleted, or named list use \enumerate{}, \itemize{}, \describe{} tags with \item tag for the individual members of the list.

  • \eqn{a + b}: inline equation.
  • \deqn{a + b}: display (block) equation

For more information see roxygen2 documentation

5.5 Documenting examples

It’s a good practice to include examples for each user-facing function in your code. These examples will be run automatically during the check() step. In some cases, you may want to avoid running the examples for some functions in your package, for example when a function might take a very long time to execute. In this case, use \dontrun{} tag.

5.6 Internal functions

Adding @export tells Roxygen that this is a function that is visible to users. If the package has some functions that should only be used internally then @export tag should not be used.

For more information and tips on how to format your documentation see the “writing R Extensions” Chapter in “Writing R Extensions” documentation