How to properly document S4 class slots using Roxygen2?

Question

For documenting classes with roxygen(2), specifying a title and description/details appears to be the same as for functions, methods, data, etc. However, slots and inheritan

Answer 1

Updated answer for Roxygen2 5.0.1, current as of 6.0.1

For S4, the best practice now is documenting using the @slot tag:

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export

On a sidenote, @exportClass is only necessary in some cases, the general way to export a function is using @export now. You also don't have to export a class, unless you want other packages to be able to extend the class.

See also http://r-pkgs.had.co.nz/namespace.html#exports

Updated answer for Roygen2 3.0.0, current as of 5.0.1.

For S4, the best practice is documentation in the form:

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

This is consistent with the internal representation of slots as a list inside the object. As you point out, this syntax is different than other lines, and we may hope for a more robust solution in the future that incorporates knowledge of inheritance -- but today that does not exist.

As pointed out by @Brian Diggs, this feature was pulled into 3.0.0, further discussion at https://github.com/klutometis/roxygen/pull/85