Para documentar classes com roxygen (2), especificar um título e descrição / detalhes parece ser o mesmo que para funções, métodos, dados, etc. No entanto, slots e herança são seu próprio tipo de animal. Qual é a melhor prática - atual ou planejada - para documentar as classes S4 no roxygen2?

Diligência devida:

Encontrei menção de uma @slotetiqueta nas primeiras descrições do roxygen. Uma postagem na lista de discussão do R-forge de 2008 parece indicar que está morta e não há suporte para o @slotroxygen:

Isso é verdade para roxygen2? A publicação mencionada anteriormente sugere que o usuário deve fazer sua própria lista detalhada com a marcação LaTeX. Por exemplo, uma nova classe S4 que estenda a "character"classe seria codificada e documentada da seguinte forma:

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

No entanto, embora isso funciona, isso \describe, \itemabordagem para documentar os slots parece inconsistente com o resto do roxygen (2), em que não há @marcas -delimited e ranhuras poderia ir indocumentados sem objeção roxygenize(). Também não diz nada sobre uma maneira consistente de documentar a herança da classe que está sendo definida. Eu imagino que a dependência ainda funcione normalmente (se um slot específico exigir uma classe não básica de outro pacote) usando a @importtag

Então, para resumir, qual é a melhor prática atual para os slots roxygen (2)?

Parece haver três opções a serem consideradas no momento:

• A - Lista detalhada (como exemplo acima).
• B - @slot... mas com tags / implementação extras eu perdi. Não foi possível fazer com que o @slot trabalhe com o roxygen / roxygen2 nas versões em que ele foi incluído como um substituto da lista detalhada no exemplo acima. Novamente, o exemplo acima funciona com roxygen (2).
• C - Alguma tag alternativa para especificar slots, como @param, que faria a mesma coisa.

Estou emprestando / estendendo esta pergunta de um post que fiz na roxygen2página de desenvolvimento no github .

Resposta atualizada para o Roxygen2 5.0.1, atual a partir do 6.0.1

Para o S4, a melhor prática agora é documentar usando a @slottag:

#' 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

Em uma nota lateral, @exportClassé necessária apenas em alguns casos, a maneira geral de exportar uma função está sendo usada @exportagora. Você também não precisa exportar uma classe, a menos que deseje que outros pacotes possam estender a classe.

Consulte também http://r-pkgs.had.co.nz/namespace.html#exports

Resposta atualizada para Roygen2 3.0.0, atual a partir de 5.0.1.

Para o S4, a melhor prática é a documentação no formato:

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

Isso é consistente com a representação interna dos slots como uma lista dentro do objeto. Como você ressalta, essa sintaxe é diferente de outras linhas, e podemos esperar uma solução mais robusta no futuro que incorpore o conhecimento da herança - mas hoje isso não existe.

Conforme apontado por @Brian Diggs, esse recurso foi trazido para a versão 3.0.0, para uma discussão mais aprofundada em https://github.com/klutometis/roxygen/pull/85

A solução fornecida pelo Full Decent está OK se você optar por documentar slots nos próprios arquivos Rd. Ao usar roxygen2, você pode usar a tag @sectionpara fazer basicamente o mesmo \describe. Um exemplo:

#' 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

roxygen2 v4.1 + e o último documento de Hadley para fazer isso:

http://r-pkgs.had.co.nz/man.html#man-classes

Ainda não testei para RC, mas funciona para mim no S4 agora.

Anteriormente

Parece que os slots de classe S4 são totalmente suportados no Roxygen2 versão 3.0+:

http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/

"documente suas classes S4, métodos S4 e classes RC com o roxygen2 - você pode remover com segurança soluções alternativas que usavam @aliase @usage, e simplesmente confiar no roxygen2 para fazer a coisa certa."