roxygen2: documenting R functions

From what I gathered on the roxygen2 package, it was perfect for me: documentation in Rd format generated automatically from the comments in the source files.

However, it took me a while to figure out how, exactly, does that work. The roxygen manual is rudimentary and technical; there is no vignette for roxygen2 and the vignette for roxygen is not applicable. I was lost and confused — so much for literate programming!

Still, once I understood how to proceed, it is truly a huge improvement in package creation. WRONG: not package creation; that was my first mistake. Roxygen does not help to maintain the package structure, and although it does update some of the package files apart from the manual pages, notably the NAMESPACE file, in general it is just for the sole purpose of maintaining the man pages. Which is a lot.

Creating the package

So, I had this source code file with several functions, and I wanted to build a package around it. First, I generated the package with the standard R package.skeleton function. I changed into the package directory, deleted the “Read-me-and-delete-me” file and modified the DESCRIPTION file (roxygen will not do it).

Second: Roxygen looks up the directory packagename/R and searches for source files which are there. So, if you want to create a man page for something, you need to have a corresponding source file. Pretty straightforward for functions that are already in the R directory. However, to create a man page for the package itself (i.e., the name-package.Rd file), one needs to create a dummy file called “name-package.R” in the R directory of the package. This file only contains the documentation in this commented, roxygen-specific format, and a single line of code containing a NULL. (that was actually one of these things which made me get stuck: in the roxygen vignette, an example is given with NA instead of NULL, which does not work, at least not in the recommended roxygen2. Also, command line examples don’t work).

To generate the manuals, start R in the parent directory of the package and run roxygenize( "packagedir" ). Presto, the manuals are there.

Using the roxygen tags to document the functions

Of course, you still need to edit the source files (including name-package.R) using the roxygen style formatting. This, fortunately, is straightforward. A block of roxygen code precedes the function to document; each line starts with #' (comment char + single quote). Several tags are necessary (notably the @export tag that indicates that the function should be exported in NAMESPACE, which I tend to forget), but this was simple to figure out.

The most important parts of the document — title, short description and details — can be included at the start of the roxygen block without any additional tags:

#' Hello world
#' 
#' The most boring program in the world
#'
#' This is so annoyingly boring that I don't even
#' know why I write it.
hello.world <- function( s="stuff it" ) 
    print( sprintf( "Go and %s, world", s ) )

So far, so good. However, this will not generate the manual: we need to mark the function for exporting. Also, we can add more tags: describes what the parameters do, who is the author, add an example.

#' Hello world
#' 
#' The most boring program in the world
#'
#' This is so annoyingly boring that I don't even
#' know why I write it.
#' @param s What the world should do and how
#' @export
#' @author God <bog@@niebo.org>
#' @examples
#' hello.world( "bugger yourself" )
hello.world <- function( s="stuff it" ) 
    print( sprintf( "Go and %s, world", s ) )

Note that @ has a special meaning for roxygen, and so it must be escaped (with another @, to be inconsistent, but practical).

Minimal example

To test this minimal example above, at least one has to do the following:

  • Create a valid DESCRIPTION file
  • Create the R directory (mkdir R)
  • Save the above code in a file in the R directory
  • Start R (in the directory where the DESCRIPTION and R reside)
  • Enter library( roxygen2 ) ; roxygenize( "." )

Roxygen will now produce a man directory in the current directory, and there, save a file called “hello.world.Rd”. This is the contents of the file:

\name{hello.world}
\alias{hello.world}
\title{Hello world}
\usage{
hello.world(s = "stuff it")
}
\arguments{
  \item{s}{What the world should do and how}
}
\description{
The most boring program in the world
}
\details{
This is so annoyingly boring that I don't even know why I
write it.
}
\examples{
hello.world( "bugger yourself" )
}
\author{
God ˂bog@niebo.org˃
}

(the < / &rt; look funny in the code above, but this is just a wordpress deficiency, the code is correct)

More good stuff

First, man pages without corresponding code. This comes in handy for all the data files and for a general package description.

You simply create an R file in the R/ directory in the source package, and call it, for example, “hello-package.R”. In this file, you write the regular roxygenize contents, but end it with a line containing NULL only:

#' Hello World Package
#' 
#' The most boring package in the world
#'
#' This is so annoyingly boring that I don't even
#' know why I write it.
NULL

This will create the manual page “hello-package.Rd” in the “man/” directory.

Links

Hadley Wickham, one of the authors of roxygen, published Advanced R Programming, an online book that includes, among other things, a tutorial for Roxygen; incomplete at best, but useful. Unfortunately, this is not easy to find and I still think that to merit a “literate programming bagde” one should document the roxygen package much better than it is documented at present.

Advertisements