Skip to content

Roxygen Guide

Jump to bottom
mb706 edited this page Aug 12, 2019 · 18 revisions

See the mlr3 Roxygen Guide for most rules.

mlr3pipelines-Specific Slots

Some mlr3pipelines specific rules when documenting PipeOps:

  • @section Internals: documents behaviour relevant mostly for development or very technical edge-case behaviour
  • @section State: documents the $state slot of a PipeOp. Should either be The `$state` is left empty (`list()`). or The `$state` is set to a named `list` with these members:, followed by the members in slot description format.
  • @section Parameters: documents the $param_set, in slot description format.
  • @name should always correspond to mlr_pipeops_<id>, where <id> is the key of the mlr_pipeops-dictionary by which the PipeOp can be constructed. For most PipeOps this should also be the default ID.

Roxygen Guide Amendments

Some amendments and clarifications:

  • Do not forget the colon (":") after @section titles!

Typename Format (<TYPENAME>)

  • S3 / R6 etc. classes are named in backticks, the topmost class only. Links to all classes that are not in R base. 
    [`Graph`]
`matrix`
`NULL`
  • For atomic types of length n, this is followed by (n), otherwise not. 
    `character(2)`
`numeric`
  • Numbers that should be integer numbers should be integer/integer(n) even if integer numbers of type numeric are accepted. 
    `integer`
`integer(7)`
  • Atomic types and lists can be prefixed with "named" 
    named `list`
named `character(2)`
  • Lists can be postfixed with of <TYPENAME> 
    `list` of `PipeOp`
  • data.table / data.frame with defined columns should have these columns named and typename given. 
    [`data.table`] with columns `name` (`character`), `constructor` (`list` of `R6ClassGenerator`)
  • Alternatives are separated by vertical bars | and possibly put in parentheses if necessary to avoid confusion. 
    `numeric` | `NULL`
    But: 
    `list` of (`character(1)` | `NULL`)
  • Special type any for no type specification 
    `any`

Slot Description Format

Used for slots / active bindings of R6 classes, for arguments of S3 or package level functions, and for parameter descriptions. Always listed in an unnumbered list. Description should end with a full stop.

Format:

* `NAME` :: <TYPENAME>\cr
  Description.

Example:

* `id` :: `character(1)`\cr
  Name of the task.
* `backend` :: (`data.table` | `DataBackend`)\cr
  Backend to use.

Method Description Format

Used for methods of R6 classes. Always listed in an unnumbered list. First line: function header (name, argument list including defaults). Second line: In-type tuple, followed by ->, followed by return type. Following lines: function description, ending with a full stop.

Functions without input ("nullary functions") have () in-type, functions that return invisible(NULL) (e.g. print, plot) have `NULL` return type. Methods that modify the R6 object itself (mutators) return self.

* nop()\cr
  () -> `NULL`\cr
  Do nothing.
* non_nop(id, names = c("Bert", "Ruediger"), attributes = list())\cr
  (`character(1)` | `NULL`, `character`, named `list`) -> [`data.table`] with columns `id` (`character`), `state` (`list` of `any`)\cr
  Does something and returns the `data.table` of the results.
* reset()\cr
  () -> `self`
  Resets the object.

Description Text Format

I.e. format of text describing slots, methods, the @description section etc.

  • R6 / S3 class names: Backtick-quoted, linked if not in base R or in any R default package. Many [`Graph`]s The [`Graph`]'s size This is a [`data.table`], not a `data.frame`
  • Field / slot names: Backtick quoted, prepended by dollar sign. The `Graph`'s `$id` Resets the `$state` to `NULL`
  • Method names: Backtick-quoted, prepended by dollar sign, followed by (). Use `$add_pipeop()` to...
  • literal strings: Backtick and double quoted: The default ID is `"pca"`.
  • functions that are not R6 object methods: Followed by (), and in brackets ([]), but not in backticks since roxygen prints them in monospace typeface automatically. Use [print()] to... This is equivalent to [data.table::copy()].

Linking

  • Simple links: [link].
  • Links to things in monospace typeface: [`link`], except functions (happens automatically): [link()]
  • Links to entities in other packages: [`package::link`], [package::link()], [`link`][package::link], [link()][package::link]
  • Linking to packages themselves: [mlr3][mlr3::mlr3-package]

@family

The @family tag creates a group of documentation pages that mutually link each other. Writing @family <TEXT> will create the line "Other : [link] [link] [link]". The following rules for this:

  • <TEXT> should be short but is allowed to, and should probably, contain spaces. It should make a natural sentence when written as "Other :". This means if it is a noun (e.g. "PipeOps") it should probably be plural.
  • A page can be member of multiple families if that is natural.
  • Do not create families with only one member.
Clone this wiki locally