There are currently no standard best practices for documentation in R6 and it is not supported directly by roxygen documentation. We document the practices that we use for consistency and as a reference for other coders. We welcome feedback and discussion about whether these are the ‘best’ practices for R6 documentation.

We use a reduced version of the Distributions R6 object for example. Each class definition is written in a separate R script with the filenames in the form “ParentClassName_ClassName.R”.


Custom Sections

We document all R6 classes using the following Roxygen tags:

  • @title - Documentation title, short and descriptive of class. Title Case.
  • @name - Name of class
  • @description - Description of class
  • @details - Details of class. Optional.
  • @section Constructor: Function and arguments to pass to constructor.
  • @section Constructor Arguments: Tabular. Gives argument names, input type and details.
  • @section Constructor Details: Any extra details required to construct the class. Optional.
  • @section Public Variables: Tabular. Variable name and return type.
  • @section Public Methods: Tabular. Method name and a link to a full documentation page. Sections separated by line breaks and bold headings.
  • @seealso - Referencing other classes. Optional.

Example

#' @include Distribution_helpers.R SetInterval_operations.R
#-------------------------------------------------------------
# Distribution Documentation
#-------------------------------------------------------------
#' @title Generalised Distribution Object
#'
#' @description A generalised distribution object for defining custom probability distributions
#'   as well as serving as the parent class to specific, familiar distributions. Common
#'   mathematical and statistical methods for distributions are defined here with approximate numerical
#'   calculations (as opposed to analytical results).
#'
#' @name Distribution
#'
#' @section Constructor: Distribution$new(name = NULL, short_name = NULL, type = NULL, support = NULL,
#' symmetric = logical(0), pdf = NULL, cdf = NULL, quantile = NULL, rand = NULL,
#' parameters = NULL, decorators = NULL, valueSupport = NULL, variateForm = NULL, description=NULL)
#'
#' @section Constructor Arguments:
#' \tabular{lll}{
#' \strong{Argument} \tab \strong{Type} \tab \strong{Details} \cr
#' \code{name} \tab character \tab Full name of distribution. \cr
#' \code{short_name} \tab character \tab Short name to identify distribution. \cr
#' \code{type} \tab SetInterval \tab Scientific type. \cr
#' }
#'
#' @section Constructor Details:
#'
#'   The most basic Distribution object consists of a name and one of pdf/cdf.
#'
#' @section Public Variables:
#'  \tabular{ll}{
#'   \strong{Variable} \tab \strong{Return} \cr
#'   \code{name} \tab Name of distribution. \cr
#'   \code{short_name} \tab Id of distribution. \cr
#'   }
#'
#' @section Public Methods:
#'  \tabular{ll}{
#'   \strong{Accessor Methods} \tab \strong{Link} \cr
#'   \code{decorators()} \tab \code{\link{decorators}} \cr
#'   \code{valueSupport()} \tab \code{\link{valueSupport}} \cr
#'   \tab \cr \tab \cr \tab \cr
#'   \strong{d/p/q/r Methods} \tab \strong{Link} \cr
#'   \code{pdf(x1, ..., log = FALSE)} \tab \code{\link{pdf}} \cr
#'   \code{cdf(x1, ..., lower.tail = TRUE, log.p = FALSE)} \tab \code{\link{cdf}}\cr
#'   \tab \cr \tab \cr \tab \cr
#'   \strong{Parameter Methods} \tab \strong{Link} \cr
#'   \code{parameters(id)} \tab \code{\link{parameters}} \cr
#'   \tab \cr \tab \cr \tab \cr
#'   \strong{Validation Methods} \tab \strong{Link} \cr
#'   \code{liesInSupport(x, all = TRUE, bound = FALSE)} \tab \code{\link{liesInSupport}} \cr
#'   \tab \cr \tab \cr \tab \cr
#'   \strong{Representation Methods} \tab \strong{Link} \cr
#'   \code{strprint()} \tab \code{\link{strprint}} \cr
#'   }
#'
#' @export
NULL
#-------------------------------------------------------------
# Distribution Definition
#-------------------------------------------------------------
Distribution <- R6::R6Class("Distribution", lock_objects = FALSE)