Exposing R functions with roxygen2


Ramiro Magno


March 31, 2022

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:

  • 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:

    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.

    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: