First, the answer to an important question: What is a “roclet”?
roxygen2package to convert
roxygen2-style documentation lines into some desired form of output.
This package currently serves to aid developers and reviewers of statistical software in aligning their software against our extensive lists of standards. In acknowledgement of Colin Gillespie’s sentiments expressed in his keynote speech at the European R Users Meeting 2020:
Standards are good
Standards should be strict
No-one reads standards
srr package aims to integrate the task of aligning software with standards within the practice of coding itself, and to make standards adherence as painless as possible.
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
@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 easiest way to install this package is via the associated
r-universe. As shown there, simply enable the universe with
And then install the usual way with,
Alternatively, the package can be installed by running one of the following lines:
remotes::install_github ("ropensci-review-tools/srr") pak::pkg_install ("ropensci-review-tools/srr")
and loaded for use with,
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
path arguments to allow functions to be applied to packages anywhere other than in the current working directory.
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.
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
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.
Enable your package to use the
srr_stats roclets by modifying the package’s
DESCRIPTION file so that the
Roxygen line looks like this:
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.
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:
##  "#' srr_stats" ##  "#'" ##  "#' All of the following standards initially have `@srrstatsTODO` tags." ##  "#' These may be moved at any time to any other locations in your code." ##  "#' Once addressed, please modify the tag from `@srrstatsTODO` to `@srrstats`," ##  "#' or `@srrstatsNA`, ensuring that references to every one of the following"
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.
@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
@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.
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
@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.
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
@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
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:
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
tests/, and well as in
.Rmd documentation files such as
README.Rmd or package vignettes. The
srr_stats roclet associated with this package is able to parse the various
@srrstats tags in all of these locations.
srr package enables standards compliance to be documented through inserting
@srrstats tags in as many locations as possible, in order to ensure compliance is documented as close as possible to the point within the code where each standard is addressed, it is not possible to insert
roxygen2 tags in every type of file. In general, standards may be inserted in any
.Rmd file, and most types of files in
inst/include directories, as long as they are used with a package able to convert documentation to a corresponding R file (such as
Rcpp’s generation of
RcppExports.R files which include the C++ documentation).
Tags may generally not be placed in any other kinds of files, including
.md files such as
CONTRIBUTING.md, or other files without extensions such as
NEWS. Standards which are best addressed in such files must be placed in some other generic location (such as
R/srr-standards.R), with a cross-reference to the file in which they are actually addressed.