Exposing R functions with roxygen2

Functions are the key building blocks of R packages. How they are exposed by developers dictates their use case.

What is there to expose about a function? Three things it turns out. Namely:

• Whether the function has an associated help page
• Whether the function is listed in the package documentation index¹
• Whether the function is internal or external

¹ To learn more about the documentation index file you may consult the section The INDEX file in the R manual on Writing R Extensions.

Wickham, Hadley, Peter Danenberg, Gábor Csárdi, and Manuel Eugster. 2022. roxygen2: In-Line Documentation for R.

Accordingly, the R package roxygen2 (Wickham et al. 2022) provides three annotation tags for the job:

• @noRd: Prevents help pages(.Rd files) from being generated
• @keywords internal: Removes the function from the package doc. index
• @export: Makes the function external

And what are the possible use cases? With increasing level of exposition, I’d paraphrase Hadley Wickham² and say that there are three main use cases:

² roxygen2 issue 1314.

1. Internal function (use no tags or the @noRd tag if source-level doc required)
2. Developer facing function (@keywords internal + @export)
3. User facing function (@export)

Here’s a breakdown of the possible NAMESPACE tags’ combinations and their use cases in the form of a cheatsheet: