How to properly document S4 class slots using Roxygen2?

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

The solution provided by Full Decent is OK if you go for documenting slots in the Rd files itself. When using roxygen2, you can use the tag @section to do basically the same with \describe. An example:

#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots: 
#'  \describe{
#'    \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#'    \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#'  }
#'
#' @note You can still add notes
#' @name EXAMPLE 
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys