R Packages, 2nd Edition

Chapter 16. Function Documentation

In this chapter, you’ll learn about function documentation, which users access with ?somefunction or help("somefunction"). Base R provides a standard way of documenting a package where each function is documented in a topic, an .Rd file (“R documentation”) in the man/ directory. .Rd files use a custom syntax, loosely based on LaTeX, and can be rendered to HTML, plain text, or PDF, as needed, for viewing in different contexts.

In the devtools ecosystem, we don’t edit .Rd files directly. Instead, we include specially formatted “roxygen comments” above the source code for each function.¹ Then we use the roxygen2 package to generate the .Rd files from these special comments.² There are a few advantages to using roxygen2:

• Code and documentation are co-located. When you modify your code, it’s easy to remember to also update your documentation.

• You can use markdown, rather than having to learn a one-off markup language that only applies to .Rd files. In addition to formatting, the automatic hyperlinking functionality makes it much, much easier to create richly linked documentation.

• There’s a lot of .Rd boilerplate that’s automated away.

• roxygen2 provides a number of tools for sharing content across documentation topics and even between topics and vignettes.

In this chapter we’ll focus on documenting functions, but the same ideas apply to documenting datasets (see “Documenting Datasets”), classes and generics, and packages. You can learn more ...