First, the answer to an important question: What is a “roclet”?

  • A roclet is an object used by the roxygen2 package to convert roxygen2-style documentation lines into some desired form of output.

The roxygen2 package parses all documentation lines from all files in the R/ directory of a package which begin with #'. Special tags beginning with @, such as @param or @export, may follow these symbols, and roclets define what is done with different kinds of tags. The roxygen2 package includes roclets to process a number of tags; the srr package implements custom roclets to process several additional tags for use with rOpenSci’s software review systems.

At present, the package only contains roclets and associated functions to help those developing and reviewing packages submitted to rOpenSci’s system for Statistical Software Review. The functions are mostly intended to ease alignment and assessment of software against the standards detailed in the main project book (from here on referred to as the “SSR Book”). The srr package can be installed with,

# install.packages("remotes")
remotes::install_github("ropenscilabs/srr")

and loaded for use with,

Both this README, and the main package vignette, describe the functionality of the package in the specific context of the statistical software review project. Both the roclet and all functions intended for use in this context are prefixed with srr_stats_. The remainder of this document is in two main sections. If you’re developing a statistics package for submission to our peer review system, keep straight on reading. If you’ve been invited to review a package, you may skip the following section and just read the subsequent section. The general procedures for both developers and reviewers are described at length in the SSR book, with this README intended to provide supporting technical details.

Note that the srr package can be applied only within the working directory of a package. There are no package or path arguments to allow functions to be applied to packages anywhere other than in the current working directory.

For Package Developers

People intending to develop packages for submission to our system for peer reviewing statistical software will need to follow the following general steps. Note that, while the srr package has a few functions which developers may call directly to aid their submission process, most functionality of this package is implemented via custom roxygen2 “roclets”. The third of the following steps describes how to link your package with srr in order to use these roclets.

  1. Ensure that your package successfully passes all autotest tests, potentially including setting test = FALSE flags to switch off any tests you consider not to be applicable to your package. For details, please see the package documentation for autotest.

  2. Decide which of our in-scope categories of statistical software best describe your package. The function srr_stats_categories() provides a list of currently developed categories for which standards have been developed, along with links to the online standards for each category:

    That function also returns links to the full descriptions of each category in the main project book. Any software within one or more of these categories may be considered for review.

  3. Enable your package to use the srr_stats roclets by modifying the package’s DESCRIPTION file so that the Roxygen line looks like this:

    Roxygen: list(markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))

    That will load the “roclet” used by this package to process the documentation of statistical standards within your actual code. Note that you do not need to add, import, or depend upon the srr package anywhere else within the DESCRIPTION file or your actual package.

  4. Load the srr package and generate lists of standards within your package’s /R folder by running, srr_stats_roxygen(category = c("<my-category-1>", "<my-category-2>")). This will by default create a new file called by default R/srr_stats_standards.R, the first few lines of which will look like this:

    The file will contain a list of all standards from your nominated categories. This file may be renamed, and the individual items moved to other locations in other files, but all nominated standards should remain in roxygen2 blocks somewhere in your source code.

    The @srrstatsVerbose line defines a variable which may be used to suppress output from the srrstats roclet when updating package documentation (by setting to FALSE). After that comes the list of standards, each of which is prefixed by a roxygen2 tag, @srrstatsTODO. A package can only be submitted once all of these TODO items have been addressed via one of the options described in the following two items.

  5. A standard may be addressed by moving the item in the srr-stats-standards.R file (or wherever you’ve chosen to list these within your own package) to one or more places in your code where these standards have been addressed. In doing so, the roxygen2 tag should be changed from @srrstatsTODO to @srrstats, and the text which initially lists the actual standard should be changed to provide a brief description of how that standard has been met. Tags for one particular standard may be repeated in multiple places within your code, and we encourage locating multiple @srrstats tags which refer to a particular standard at all locations which directly address that standard.

  6. Alternatively, any standards which you consider not applicable to your software may remain listed in the templated section of the main srr-stats-standards.R document (or any alternative location), with their tag changed from @srrstatsTODO to @srrstatsNA, and the description of the standard removed and replaced by an explanation of why you consider that standard not to be applicable to your software. These @srrstatsNA tags should be collected together within a single roxygen2 block with a title of NA_standards, as provided in the initial template generated by the srr_stats_roxygen() function. Any non-applicable standards can then just be moved into this block, with their @srrstatsTODO tags changed to @srrstatsNA

  7. Each time you run devtools::document() or the equivalent roxygen2::roxygenise(), the roclet will scan your package’s documentation for the state of standards, and will generate a summary of the result on your screen.

To help developers understand how to use these roclets, this package includes a function, srr_stats_pkg_skeleton(), which will generate a skeleton of a package with several roxygen2 tags inserted throughout the code. This function returns the directory where the skeleton package has been created, so running the following two lines will illustrate the roclets in action:

d <- srr_stats_pkg_skeleton ()
roxygen2::roxygenise (d)

Note that the skeleton package also includes C++ code in a src/ directory, so will be compiled the first time your run roxygensise(). Running a second time will generate cleaner output from the srr_stats roclets only. The tags included in roxygen2 blocks in this skeleton package may be modified, moved, copied, and changed in any way you like to help you understand how the roclets work. Simply play around with the roxygen2 lines and run roxygensise() each time to see the effect. Individual standards may be moved to, and addressed in, any location including the directories R/, src/, or tests/. The srr_stats roclet associated with this package is able to parse the various @srrstats tags in all of these locations.