Roxygen Guide

R6 Classes

• Document NULL instead of the class itself to get more flexibility. Note that you must provide @name.
• Documentation contains the following elements:
  1. Each documentation starts with an @title section (explicitly declaring it as title), followed by a newline.
  2. Next comes an @description which describes the general purpose of the class.
  3. The "Usage" section must be manually created with @section Usage:. a) If the class inherits from another class, this should be the first information. b) The construction of the class, with assignment to an examplary variable. c) 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. d) All methods (except clone(), print() and format()), in alphabetical order. Include all arguments and defaults. e) All S3 methods defined for the class.
  4. Section "Arguments". Each argument should contain its type / class and a short description. If you have trouble describing an argument because it has a different function in different methods, try to find better names for the variables.
  5. 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 member and methods, respectively.
• 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.

Example Documentation

#' @title ClassFoo
#'
#' @name ClassFoo
#' @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

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