Skip to main content

Writing R Package Documentation

Posit Support
  • Updated

Writing Package Documentation

Overview

One of the core requirements for R packages is that all exported functions, objects, and datasets have complete documentation. RStudio includes several tools to assist in the creation of documentation, including:

  • Support for the roxygen2 package, including editor syntax-awareness and the ability to automatically invoke roxygen2 prior to package builds.
  • The ability to edit, preview, and spell-check Rd files.
  • Support for authoring and previewing package vignettes using Sweave and knitr.

Note that you will need to install the roxygen2 package first ( install.packages("roxygen2") ) before these advanced features and settings will appear in the IDE. 

Using roxygen2

The roxygen2 package provides an in-source documentation system that automatically generates R documentation (Rd) files. For example, the following special roxygen comments result in the automatic generation of an Rd file for the autoplot function:

RStudio includes syntax-highlighting, code-completion, and automatic line-wrapping for roxygen comments. RStudio also includes a Reflow Comment command that will automatically re-wrap multiline roxygen comments.

Roxygenizing a Package

You can use Project Options : Build Tools to configure Roxygen to run whenever you execute certain package build commands:

Using roxygen for package documentation is generally much easier than composing Rd files directly and is highly recommended for new package documentation.

Roxygen also plays a prominent roll in the devtools package, a package developed by Hadley Wickham of RStudio that makes it easier to build and document R packages. To learn more about roxygen and devtools, visit Hadley's book R Packages, freely accessible online.

Rd Files

RStudio also includes extensive support for authoring R documetnation (Rd) files directly. Rd files use a simple markup format that syntactically resembles LaTeX. For detailed documentation on the Rd format please see the article on Writing R Documentation available on CRAN.

Creating Rd Files

Rd files are saved in the man directory of an R package. You can create a new Rd file for an existing function, dataset, or other object in two ways:

  • Call the prompt or promptData function, and then move the resulting Rd file into the man directory.
  • Use the File -> New -> R Documentation command in RStudio. This command will allow you to specify the name of an existing function or dataset to use as the basis for the Rd file or alternatively will create a new empty Rd file.

The RStudio editor includes syntax highlighting and spell-checking facilities for Rd files.

Previewing Rd Files

While authoring Rd files you can get a quick preview of what the Rd file will look like when rendered as HTML. To do this you can use the Preview HTML command:

This will render the Rd file as HTML in the RStudio Help pane. Note that by checking the Preview on Save option you can have the HTML preview automatically refreshed every time you save the Rd file.

 

 

Related Topics

Related articles