Roxygen Guide

Documentation Style Guide

There is no official way to document R6 classes using roxygen (as discussed here). This style guide describes our agreement on how to document R6 classes for mlr3 packages with roxygen/markdown.

Examples can be found in the function reference, the respective source files are linked at the top of the respetive manual page.

Structure

Title

The title should be in title case:

All principial words capitalized
Articles, conjunctions or prepositions are all lowercase

#' @title Regression Task

Usage

The usage section for R6 objects is not useful and must be suppressed.

#' @usage NULL

Format

The format specification.

Base classes:

#' @format [R6::R6Class] object.

Derived classes:

#' @format [R6::R6Class] object inheriting from [Task]/[TaskSupervised].

Includes

If the class inherits from another class which is implemented in the same package but in a different file, it is required to control the collation order:

#' @include TaskSupervised.R

Constructor

Describes how to instantiate the class. To mimick R's "Usage", this section should start with a code block (three backticks) where an exemplary assignment to some variable with a short name is done:

#' @section Construction:
#' ```
#' t = TaskSupervised$new(id, task_type, backend, target)
#' ```

In the following, refer to the instance as t, e.g. t$id.

Next, each argument of the constructor needs to be documented in an itemize environment. The first line of each bullet point consists of the argument name in backticks, followed by the separator "::" and the expected type of the argument. If the argument is not type-safe, try to list all possible input types. Use additional lines to further describe the purpose of the argument.

#' * `id` :: `character(1)`\cr
#'   Name of the task.
#' * `backend` :: ([DataBackend] | `data.frame()` | ...)\cr
#'   Either a [DataBackend], or any object which is convertible to a DataBackend with `as_data_backend()`.
#'   E.g., a `data.frame()` will be converted to a [DataBackendDataTable].

Fields

Describe all fields of the R6 class, i.e. everything public which is not a function. This is done in the same format as the arguments in the constructor.

#' @section Fields:
#' * `formula` :: `formula()`\cr
#'   Constructs a [stats::formula], e.g. `[target] ~ [feature_1] + [feature_2] + ... + [feature_k]`, using
#'   the active features of the task.

It is possible to copy over the contents of the section from another class via:

#' @inheritSection Task Fields

Methods

Describes public methods. The first line in each bullet point gives the signature of the method. The second line contains the classes of all arguments in backticks (linked if not default R package classes; possibly with length given in parentheses if vector type). Alternative classes get separated by vertical bars (|), different arguments comma-separated, all surrounded by parentheses. Spaces before and after |, after ,, but not after ( or before ) or ,. The class definition is followed by an arrow (->), followed by return type. Use return type self if the method is a mutator. Functions without input ("nullary functions") have () in-type, functions with invisible(NULL) (e.g. print, plot) have `NULL` return type.

#' * `missings(cols = NULL)`\cr
#'   `character()` -> named `integer()`\cr
#'   Returns the number of missing values observations for each columns in `cols`.
#'   Argument `cols` defaults to all columns with role "target" or "feature".
#'
#' * `data(rows = NULL, cols = NULL, format = NULL)`\cr
#'   (`integer()` | `character()`, `character()`, `character(1)`) -> `any`\cr
#'   Returns a slice of the data from the [DataBackend] in the format specified by `format`
#'   (depending on the [DataBackend], but usually a [data.table::data.table()]).
#'   Rows are subsetted to only contain observations with role "use".
#'   Columns are filtered to only contain features with roles "target" and "feature".
#'   If invalid `rows` or `cols` are specified, an exception is raised.

S3 Methods

Describes S3 methods which are applicable on instantiated objects. Uses the same format as regular methods.

#' * `as.data.table(t)`\cr
#'   [Task] -> [data.table::data.table()]\cr
#'   Returns the data set as `data.table()`.

Family

If there are multiple related classes, it is advised to group them together into families:

#' @family Task

Each member of the family will get cross-references to other family members in a "See also" section.

Export

Export only if you want to expose the class to the user. If the class is intended to be used by another package, but not by the user, add the keyword internal to hide it from the documentation overview:

#' @export
#' @keywords internal

Examples

Keep them simple and fast. Also consider inserting some comments.

#' # construct a new task
#' task = Task$new("iris", task_type = "classif", backend = iris)
#'
#' # retrieve the number of rows
#' task$nrow
#'
#' # retrieve the number of columns
#' task$ncol

Text Style Guide

Refer to fields and methods with a prepended dollar sign to avoid confusion with regular variables or functions ($id).
Refer to methods with a prepended dollar and an appended empty pair of parentheses to avoid confusion with regular variables or functions (missings()).
Make use of explicit links for:
- Every function that is not an R6 method.
- Any type / class that is not in R default packages
- Every type, class, function that is not in R default packages in a member var type description or function type description.
Don't link things like "character(1)" or "character()".