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 @slot
etiqueta 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 @slot
roxygen:
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
, \item
abordagem 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 @import
tag
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 roxygen2
página de desenvolvimento no github .
setClass
instruções do que setMethod
. Fazer a alteração uma vez @slot
implementada não será muito doloroso.
@slot
é provavelmente o que você quer a longo prazo, mas tem que ser implementado pela primeira vez ...