Roxygen Guide

R6 Classes

• Document NULL instead of the class itself to get more flexibility. Note that you must provide @name.
• Use @keywords internal for classes which are mostly used internally.
• Use @family for all classes which belong to a common parent class, including the parent class.
• Remember to @include TheBaseClass.R if the parent class lives in another file in the same package to make sure that the collation order is set correctly in DESCRIPTION.

Sections

1. Start with a @title section (explicitly declaring it as title), followed by a newline.
2. Provide a @name for roxygen.
3. Provide a @format tag. This should link to R6 and additionally all parent classes.
4. Next comes an @description which describes the general purpose of the class.
5. The "Usage" section must be manually created with @section Usage. It should contain the following information:
   1. If the class inherits from another class, this should be the first information.
   2. The construction of the class, with assignment to an examplary variable.
   3. All members, in alphabetical order. This includes active bindings. If the member is intendend to be set by the user, include an extra line with an assignment.
   4. All methods (except clone(), print() and format()), in alphabetical order. Include all arguments and defaults.
   5. All S3 methods defined for the class.
6. Section "Arguments". Describe each argument used in the construtctor, as right-hand side of an assignment or as an argument in a method. Include the expected class / type of each argument. If you have trouble describing an argument because it has a different type in different places, try to find better names to distinguish these variables.
7. Section "Details". A short description for each member and each method, in the same order as listed in "Usage". Make sure to document the type or return value for members and methods, respectively.

Example Documentation

#' @title ClassFoo
#'
#' @name ClassFoo
#' @format [R6Class] object inheriting from [TheBaseClass].
#' @description 
#' This is the description of class foo. Its only purpose is this
#' documentation example.
#'
#' @section Usage:
#' Inherits from [TheBaseClass]. 
#'
#' ```
#' # Construction
#' f = ClassFoo$new(argument1)
#'
#' # Members
#' f$id
#' f$id = id
#' f$member
#'
#' # Methods
#' f$method1(argument2 = 123)
#' f$method2()
#' ```
#' 
#' @section Arguments:
#' * `argument1` ([R6 class] or `type`):
#'   Description of argument1
#' * `argument2` (`integer()`):
#'   Description of argument1
#' * `id` (`character(1)`): 
#'   Identifier for the instance.
#’
#' @section Details:
#' * `id`: A short descriptive identifier.
#' * `member`: Description of member. 
#' * `method1()` ([data.table::data.table()]): Description of method1. The returned data table has two columns: ...
#' * `method2()` (`logical(1)`): Description of method2. Return `TRUE` if some condition holds.
#'
#' @family TheBaseClass
#'
#' @examples
#' f = ClassFoo$new("hello", 123)
#' f$method1(10)
NULL

#' @include TheBaseClass.R
#' @export
ClassFoo = R6Class("ClassFoo", inherit = TheBaseClass)