Para documentar clases con roxygen (2), especificar un título y una descripción / detalles parece ser lo mismo que para funciones, métodos, datos, etc. Sin embargo, las ranuras y la herencia son su propio tipo de animal. ¿Cuál es la mejor práctica, actual o planificada, para documentar clases S4 en roxygen2?
Debida diligencia:
Encontré mención de una @slot
etiqueta en las primeras descripciones de roxygen.
Una publicación de la lista de correo de R-forge de 2008
parece indicar que esto está muerto, y no hay soporte para @slot
roxygen:
¿Es esto cierto de roxygen2? La publicación mencionada anteriormente sugiere que un usuario debe hacer su propia lista detallada con marcado LaTeX. Por ejemplo, una nueva clase S4 que extiende la "character"
clase se codificaría y documentaría de la siguiente manera:
#' 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"
)
Sin embargo, aunque esto funciona, este \describe
, \item
método para documentar las ranuras parece inconsistente con el resto de roxygen (2), en la que no hay @
etiquetas -delimited y ranuras podrían ir indocumentado sin objeciones por parte de roxygenize()
. Tampoco dice nada sobre una forma consistente de documentar la herencia de la clase que se está definiendo. Me imagino que la dependencia todavía funciona bien (si una ranura en particular requiere una clase no base de otro paquete) usando la @import
etiqueta.
Entonces, para resumir, ¿cuál es la mejor práctica actual para las ranuras roxygen (2)?
Parece que hay tres opciones a considerar en este momento:
- A - Lista detallada (como el ejemplo anterior).
- B -
@slot
... pero con etiquetas / implementación adicionales que perdí. No pude hacer que @slot funcionara con roxygen / roxygen2 en versiones en las que se incluyó como reemplazo de la lista detallada en el ejemplo anterior. Nuevamente, el ejemplo anterior funciona con roxygen (2).- C: alguna etiqueta alternativa para especificar ranuras, como
@param
, que lograría lo mismo.
Estoy tomando prestada / extendiendo esta pregunta de una publicación que hice en la roxygen2
página de desarrollo en github .
setClass
declaraciones que setMethod
. Hacer el cambio una vez @slot
implementado no será demasiado doloroso.
@slot
es probablemente lo que desea a largo plazo, pero debe implementarse primero ...