Introduction to roxygen2

Hadley Wickham


Documentation is one of the most important aspects of good code. Without it, users won’t know how to use your package, and are unlikely to do so. Documentation is also useful for you in the future (so you remember what the heck you were thinking!), and for other developers working on your package. The goal of roxygen2 is to make documenting your code as easy as possible. R provides a standard way of documenting packages: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on latex. Roxygen2 provides a number of advantages over writing .Rd files by hand:

As well as generating .Rd files, roxygen will also create a NAMESPACE for you, and will manage the Collate field in DESCRIPTION.

This vignette provides a high-level description of roxygen2 and how the three main components work. The other vignettes provide more detail on the individual components:

Running roxygen

There are three main ways to run roxygen:

As of version 4.0.0, roxygen2 will never overwrite a file it didn’t create. It does this by labelling every file it creates with a comment: “Generated by roxygen2: do not edit by hand”.