5 Documenting functions

The output of our check tells us that we are missing documentation for the make_shades function. Writing this kind of documentation is another part of package development that has been made much easier by modern packages, in this case one called roxygen2. R help files use a complicated syntax similar to LaTeX that can be easy to mess up. Instead of writing this all ourselves using Roxygen lets us just write some special comments at the start of each function. This has the extra advantage of keeping the documentation with the code which make it easier to keep it up to date.

5.1 Adding documentation

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

Roxygen comments all start with #'. The first line is the title of the function then there is a blank line. Following that there can be a paragraph giving a more detailed description of the function. Let’s fill those in to start with.

The next section describes the parameters (or arguments) for the function marked by the @param field. RStudio has helpfully filled in names of these for us but we need to provide a description.

The next field is @return. This is where we describe what the function returns. This is usually fairly short but you should provide enough detail to make sure that the user knows what they are getting back.

After @return we have @export. This field is a bit different because it doesn’t add documentation to the help file, instead it modifies the NAMESPACE file. Adding @export tells Roxygen that this is a function that we want to be available to the user. When we build the documentation Roxygen will then add the correct information to the NAMESPACE file. If we had an internal function that wasn’t meant to be used by the user we would leave out @export.

The last field in the skeleton is @examples. This is where we put some short examples showing how the function can be used. These will be placed in the help file and can be run using example("function"). Let’s add a couple of examples. If you want to add a comment to an example you need to add another #.

Other fields

In this example we only fill in the fields in the skeleton but there are many other useful fields. For example @author (specify the function author), @references (any associated references) and @seealso (links to related functions).

5.2 Building documentation

Now we can build our documentation using devtools.

Updating mypkg documentation
Updating roxygen version in C:\Users\USER\Desktop\mypkg/DESCRIPTION
Writing NAMESPACE
Loading mypkg
Writing NAMESPACE
Writing make_shades.Rd

The output shows us that devtools has done a few things. Firstly it has set the version of roxygen2 we are using in the DESCRIPTION file by adding this line:

RoxygenNote: 6.1.1

Next it has updated the NAMESPACE file. If you open it you will see:

Which tells us that the make_shades function is exported.

The last thing it has done is create a new file called make_shades.Rd in the man/ directory (which will be created if it doesn’t exist). The .Rd extension stands for “R documentation” and this is what is turned into a help file when the package is installed. Open the file and see what it looks like.

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/colours.R
\name{make_shades}
\alias{make_shades}
\title{Make shades}
\usage{
make_shades(colour, n, lighter = TRUE)
}
\arguments{
\item{colour}{The colour to make shades of}

\item{n}{The number of shades to make}

\item{lighter}{Whether to make lighter (TRUE) or darker (FALSE) shades}
}
\value{
A vector of n colour hex codes
}
\description{
Given a colour make n lighter or darker shades
}
\examples{
# Five lighter shades
make_shades("goldenrod", 5)
# Five darker shades
make_shades("goldenrod", 5, lighter = FALSE)
}

Hopefully you can see why we want to avoid writing this manually! This is only a simple function but already the help file is quite complicated with lots of braces. To see what the rendered documentation looks like just run ?make_shades.

5.3 Formatting documentation

The rendered output already looks pretty good but we might want to add some extra formatting to it to make it a bit clearer. As we have seen above there is a special syntax for different kinds of formatting. For example we can mark code in the documentation using \code{}.

Run devtools::document() again and see what has changed in the rendered file. There are many other kinds of formatting we could use, for example: \code{}, \eqn{}, \emph{}, \strong{}, \itemize{}, \enumerate{}, \link{}, \link[]{}, \url{}, \href{}{}, \email{}.

Using Markdown

If you are familiar with Markdown you may prefer to use it for writing documentation. Luckily Roxygen has a Markdown mode that can be activated using usethis::use_roxygen_md(). See the Roxygen Markdown vignette for more details https://cran.r-project.org/web/packages/roxygen2/vignettes/markdown.html.