Tutorial: Literate programming with Roxygen

Peter Danenberg, Computer Science Department, University of Southern California, USA
Manuel Eugster, Workgroup Computational Statistics, Department of Statistics, Ludwig-Maximilians-Universität Munich, Germany


Synchronizing source code, documentation and package metadata is particularly error-prone. Roxygen makes this task easier by enabling literate programming for the R language. See the project webpage for more details.

The concept of literate programming is to combine documentation with source code to simplify consistency between them. A common approach defines a special comment block along with various descriptive tags signifying conceptual parts of source code. The system then processes these special comment blocks and generates the documentation. Well-known systems are JavaDoc for the Java and Doxygen for the C/C++ language.

Roxygen implements this idea for the R language. The package defines a Roxygen block as lines of special comments which are prefaced with #', and tags beginning with an @ sign. Roclets handle these tags and process them to some outcome; e.g., the Rd-Roclet handles Rd related tags and creates the corresponding Rd files. In addition to the in-source documentation, Roxygen extends this concept and defines directives to namespace, description and file collation handling.

The tutorial will demonstrate how Roxygen assists during all parts of package creation via a small example. The example will include the generation of Rd and NAMESPACE files, collate directives and callgraphs. Roxygen's high extensibility, which allows it to conform to individual needs, will be illustrated by development of an additional example.


Use Roxygen Extend Roxygen

Potential attendees

R programmers who document code or maintain packages; basic knowledge of R and R packages will be assumed.