Documenting S4

Generics

S4 generics are functions, so document them as such. @export a generic if you want users to call it or other developers to write methods for it. If the generic is internal, you don’t need to export or document it.

Classes

Document S4 classes by adding a roxygen block before setClass(). @export a class if you want users to create instances or other developers to extend it (e.g. by creating subclasses). Internal classes don’t need documentation. Use @slot to document the slots of the class. Here’s a simple example:

#' An S4 class to represent a bank account
#'
#' @slot balance A length-one numeric vector
#' @export
Account <- setClass("Account", slots = list(balance = "numeric"))

Methods

S4 methods are a little more complicated. Unlike S3 and S7 methods, all S4 methods must be documented. You only need to @export a method if the generic lives in another package.

You can document methods in three places:

• In the class. Most appropriate if the corresponding generic uses single dispatch and you created the class.

• In the generic. Most appropriate if the generic uses multiple dispatches and you control it.

• In its own file. Most appropriate if the method is complex or the either two options don’t apply.

Use either @rdname or @describeIn to control where method documentation goes. See vignette("reuse") for more details.