R Packages

Chapter 5. Object Documentation

Documentation is one of the most important aspects of a good package. Without it, users won’t know how to use your package. Documentation is also useful for “future you” (so you remember what your functions were supposed to do), and for developers extending your package.

There are multiple forms of documentation. In this chapter, you’ll learn about object documentation, as accessed by ? or help(). Object documentation is a type of reference documentation. It works like a dictionary: while a dictionary is helpful if you want to know what a word means, it won’t help you find the right word for a new situation. Similarly, object documentation is helpful if you already know the name of the object, but it doesn’t help you find the object you need to solve a given problem. That’s one of the jobs of vignettes, which you’ll learn about in the next chapter.

R provides a standard way of documenting the objects in a package: you write .Rd files in the man/ directory. These files use a custom syntax, loosely based on LaTeX, and are rendered to HTML, plain text, and PDF for viewing. Instead of writing these files by hand, we’re going to use roxygen2, which turns specially formatted comments into .Rd files. The goal of roxygen2 is to make documenting your code as easy as possible. It has a number of advantages over writing .Rd files by hand:

• Code and documentation are intermingled so that when you modify your code, you’re reminded to also update your documentation. ...