In this final post of the six part series on R package integration with modern reusable C++ Code using Rcpp, we will look at providing documentation for an R package. To review, we previously covered the following topics:
- Installation and configuration of an
Rcpppackage project in RStudio - Design considerations for integrating R with reusable C++ code
- Rcpp interface code examples that are exported to R
- Creating an Rcpp Package Project in RStudio, and building and distributing an R package
- An introductory example of integrating independent and standard C++ code in an R package, with sample code provided on GitHub
Let’s now look at how to provide html documentation that conforms to the familiar form one finds in R packages.
Documentation
In the discussion that follows, we will look at a quick and relatively easy way to provide documentation for each of the C++ functions that is exported as an R function in an Rcpp-based package. It should be noted that there are alternatives that are often preferred for packages that are submitted to CRAN for publication; for example, using the ROxygen2 package for generating the documentation from inline statements in the interface code. This, however, involves sophistication and complexity beyond the scope of this “getting started” series.
The approach we will examine here involves filling a file template for each exported function, as well as a file that provides information common to the entire package. These file templates carry an Rd extension, as we shall see. The corresponding html files are then generated when you build your package. The good news is that RStudio makes this a relatively painless process.
If you create an Rcpp package project as discussed in the previous posts in this series, you will find the following two files provided by default under the man subdirectory:
Default documentation files
These files are provided by default. You ultimately won’t need the hello world help file, but the RcppProject-package.Rd will contain common information for the entire package; this latter file will be introduced shortly.
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
The Check Package Utility
After building and testing your package as discussed earlier on, there is one more task that one should run before deploying an R package, and this is the Check Package procedure, which can be found under the Build menu in RStudio:
Starting the Check Package process
As described in the R documentation (devtools), Check Package “automatically builds and checks a source package, using all know best practices”. While this is more of a critical step for submitting a package to CRAN, even for internal deployment it’s a good idea to run it to be sure that your documentation is complete, and the examples in your documentation run properly. If you are missing an .Rd file for a function exported to your package, or if an example in your documentation does not run, the check procedure will flag an error.
The heavy details related to checking a package for CRAN submission are located on the CRAN website, and of course many other sources are available on the internet. These are beyond the scope of this series, but if at some point you are contemplating a CRAN submission, it will be necessary to work through the details.
Summary
This concludes our series on integrating independent, standard, and reusable C++ code in an R package using RStudio and the Rcpp package. Hopefully, this will help you avoid some of the frustrations one can encounter from the proverbial fire hose of ubiquitous information that often obscures the essentials at the outset. Happy packaging!
You may leave a comment below or discuss the post in the forum community.rstudio.com.