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