There are three things that you might document for S4:
- Generics: document as functions; mention that they are generics.
- Methods: unlike S3/S7, all S4 methods must be documented.
-
Classes: document the class definition and use
@slotfor slots.
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.