R Package Integration with Modern Reusable C++ Code Using Rcpp – Part 6

Default documentation files

Documentation for Exported Functions

Let’s first cover how to create a help file for an exported Rcpp interface function. To show this, let’s go back to the sample code provided on GitHub for Part 5. Suppose you wanted to provide documentation for the rAdd(.) function that is exported from the CppInterface.cpp file. How would you do this?

With RStudio, the solution is quite easy. First, you would select New File/Documentation... from the File menu at the top:

You will then see an input panel as follows. Under Topic name, type in the function name rAdd, and be sure the selection under Rd template is set to function (the default):

New R documentation file selection

After clicking OK, you will see the rAdd.Rd file appear in the man subdirectory in the RStudio files pane:

New documentation file in man folder

Next, double click on this file to open it in RStudio. Note that RStudio is smart enough to glean the proper number of arguments from the function and place this information in the file:

Top of the created rAdd.Rd file

Work down the file section by section and replace the comments in green (beginning with a % character) with the relevant information as described to fill in the necessary information; also, the commented line: %- Also NEED an '\alias' for EACH other topic documented here. can just be removed. The contents for each section should be placed inside the curly brackets { } following each of the following items, as will be demonstrated in the example that follows these descriptions.

name and alias: Just leave these as they are, with the function name.

title: Provide brief description of what the function does .

description: Provide a more detailed description of what the function does.

usage: The easiest thing to do here is to leave it as is.

arguments: You will notice the description of each argument x and y is nested. Just enter the type of each variable, and a short description of each if desired.

details: This can be removed if no further details are required; otherwise, place additional details about the functionality here.

value: Indicate the return type here.

references: Place references you wish to cite here; otherwise, this can be removed if not needed.

author: Provide the names of authors/contributors for this package function.

note and seealso: Enter any additional information about the function; may be removed if not needed.

examples: Place working example(s) of your function here. This should be completely self-contained, including any input data (if needed).

After the examples section, remove the trailing comments at the bottom of the file.

A complete sample file could then be as follows. You could also use this as a blueprint for your own function documentation if you wish.

\name{rAdd}
\alias{rAdd}
\title{Add two numbers}
\description{Adds two real numbers}
\usage{
rAdd(x, y)
}
\arguments{
  \item{x}{A real number}
  \item{y}{A real number}
}
\details{This is a trivial example}
\value{numeric}
\references{Courant and Hilbert, Methods of Mathematical Physics, Volumes 1 & 2}
\author{Fred Sanford}
\note{Nothing to say}
\seealso{https://rviews.rstudio.com/}
\examples{
x <- 586.3
y <- 922.6
rAdd(x, y)
}

To generate the html help file, rebuild your project. When complete, and with the package reloaded into your current R session, look up rAdd in the usual help section in RStudio. The result should look like this:

The generated help file for the rAdd(.) function

As a matter of best practice, you will want to follow the same instructions per the above for all of the remaining exported interface functions in your package. The remaining .Rd files have been uploaded to the man directory in the GitHub repository for this post. These help files accompany the source files that were provided for Part 5.

Documentation of Common Package Information

A default file is also provided with an RStudio Rcpp project that is to contain an overall help file for the entire package; it is of the form PackageName-package.Rd. However, modifying this file for your particular package can sometimes be a source of build errors and package check errors, so I recommend just keeping it simple, at least until you become more accustomed to writing your own R packages. In particular, you will probably save yourself some trouble by removing the code examples section from this file and relegating them to the individual function help files, at least to get started.

As an example, the RcppBlogCode-package.Rd file is also included in the GitHub folder for this post, as noted above. As you can see, this is short and sweet, but if applied to a realistic situation, it should be reasonably informative. The generated result is shown here:

Generated help file containing common package information

Starting the Check Package process