Como documentar adequadamente os slots de classe S4 usando Roxygen2?

Question

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 prática recomendada - atual ou planejada - para documentar as classes S4 no roxygen2?

Due Diligence:

Encontrei menção a uma tag @slot nas primeiras descrições do roxygen. Uma postagem na lista de discussão R-forge de 2008 parece indicar que isso está morto, e não há suporte para @slot em roxygen:

Isso é verdade para o roxygen2? A postagem mencionada anteriormente sugere que o usuário deve fazer sua própria lista de itens com marcação LaTeX. Por exemplo. uma nova classe S4 que estende a classe "character" seria codificada e documentada assim:

#' 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 funcione, esta abordagem \describe, \item para documentar os slots parece inconsistente com o resto do roxygen (2), pois não há tags delimitadas por @ e os slots podem ficar indocumentados sem objeção de roxygenize(). Também não diz nada sobre uma maneira consistente de documentar a herança da classe que está sendo definida. Imagino que a dependência geralmente ainda funcione bem (se um determinado slot requer uma classe não-base de outro pacote) usando a tag @import.

Então, para resumir, qual é a prática recomendada atual para 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 que perdi. Não consegui fazer o @slot funcionar com roxygen / roxygen2 nas versões onde foi incluído como um substituto para a 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 pegando emprestado / estendendo esta pergunta de uma postagem que fiz para a página de desenvolvimento roxygen2 no github .

Answer 1

roxygen2 v4.1 + e o documento mais recente de Hadley para fazer isso:

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

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

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 roxygen2 - você pode remover com segurança soluções alternativas que usavam @alias e @usage e simplesmente contar com roxygen2 para fazer a coisa certa."

Answer 2

Resposta atualizada para Roxygen2 5.0.1, atual a partir de 6.0.1

Para S4, a prática recomendada agora é documentar usando a tag @slot:

#' 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 só é necessário em alguns casos, a maneira geral de exportar uma função é usar @export agora. Você também não precisa exportar uma classe, a menos que queira 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 S4, a prática recomendada é 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ê apontou, essa sintaxe é diferente das outras linhas, e podemos esperar uma solução mais robusta no futuro que incorpore o conhecimento de herança - mas hoje isso não existe.

Conforme apontado por @Brian Diggs, este recurso foi puxado para 3.0.0, discussão adicional em https://github.com/klutometis/roxygen/pull/85

Answer 3

A solução fornecida pela Full Decent está OK se você for documentar slots nos próprios arquivos Rd.Ao usar roxygen2, você pode usar a tag @section para fazer basicamente o mesmo com \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