¿Cómo documentar correctamente las ranuras de clase S4 usando Roxygen2?
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 las clases S4 en roxygen2?
Debida diligencia:
Encontré una mención de una @slotetiqueta 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 que no hay soporte para @slotroxygen:
¿Es esto cierto para roxygen2? La publicación mencionada anteriormente sugiere que un usuario debería crear su propia lista detallada con marcado LaTeX. Por ejemplo, una nueva clase S4 que amplíe la "character"clase se codificaría y documentaría así:
#' 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 \describeenfoque \itempara documentar las ranuras parece inconsistente con el resto de roxygen(2), en el sentido de que no hay @etiquetas delimitadas y las ranuras podrían quedar sin documentar sin ninguna objeción por parte de roxygenize(). Tampoco dice nada sobre una forma coherente de documentar la herencia de la clase que se está definiendo. Me imagino que la dependencia generalmente todavía funciona bien (si una ranura en particular requiere una clase no base de otro paquete) usando la @importetiqueta.
Entonces, para resumir, ¿cuál es la mejor práctica actual para las ranuras roxygen(2)?
Parece haber tres opciones a considerar en este momento:
- A: lista detallada (como en el ejemplo anterior).
- B --
@slot... pero con etiquetas/implementación adicionales me perdí. No pude hacer que @slot funcionara con roxygen/roxygen2 en versiones en las que se incluía 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/ampliando esta pregunta de una publicación que hice en la roxygen2página de desarrollo en github .
Respuesta actualizada para Roxygen2 5.0.1, vigente a partir de 7.2.0
Para S4, la mejor práctica ahora es documentar usando la @slotetiqueta:
#' 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
Como nota al margen, solo es necesario en algunos casos; ahora @exportClassse utiliza la forma general de exportar una función . @exportTampoco es necesario exportar una clase, a menos que desee que otros paquetes puedan ampliar la clase.
Véase también http://r-pkgs.had.co.nz/namespace.html#exports
Respuesta actualizada para Roygen2 3.0.0, vigente a partir de 5.0.1.
Para S4, la mejor práctica es la documentación en el formato:
#' \section{Slots}{
#' \describe{
#' \item{\code{a}:}{Object of class \code{"numeric"}.}
#' \item{\code{b}:}{Object of class \code{"character"}.}
#' }
#' }
Esto es coherente con la representación interna de las ranuras como una lista dentro del objeto. Como usted señala, esta sintaxis es diferente a otras líneas, y podemos esperar una solución más sólida en el futuro que incorpore el conocimiento de la herencia, pero hoy eso no existe.
Como señaló @Brian Diggs, esta característica se incorporó a la versión 3.0.0; se analiza más en https://github.com/klutometis/roxygen/pull/85
La solución proporcionada por Full Decent está bien si opta por documentar espacios en los archivos Rd. Al usar roxygen2, puedes usar la etiqueta @sectionpara hacer básicamente lo mismo con \describe. Un ejemplo:
#' 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
