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 index1
- Whether the function is internal or external
1 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 Wickham2 and say that there are three main use cases:
2 roxygen2 issue 1314.
- Internal function (use no tags or the
@noRdtag if source-level doc required) - Developer facing function (
@keywords internal+@export) - User facing function (
@export)
Here’s a breakdown of the possible NAMESPACE tags’ combinations and their use cases in the form of a cheatsheet:
