Tutorial: Literate programming with Roxygen

Abstract

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.

Outline

• Rd files
• Basic in-source documentation using basic Rd directives, e.g. @param, @examples
• Class documentation using S4 directives, e.g. @setClass
• NAMESPACE file
• Handling the name space management system using NAMESPACE directives, e.g. @export
• DESCRIPTION file
• Controlling the collation order for R code files using collate directives, e.g. @include
• Basic program analysis
• Visualizing calling relationships between functions using the callgraph directives, e.g. @callGraphDepth

• Roxygen framework
• Roxygen mini-language and its parse tree
• Roclets, the modular framework for transformations
• Core roclets, e.g. Rd-roclet
• Own roclets
• Roclet from scratch

Potential attendees

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