¿Cómo documentar correctamente las ranuras de clase S4 usando Roxygen2?
Para documentar clases con roxygen(2), especificar un título y 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 current actual o planificada?para documentar las clases S4 en roxygen2?
Diligencia debida:
Encontré mención de una etiqueta @slot en las primeras descripciones de roxygen.
A 2008 R-forge mailing list post
parece indicar que esto está muerto,
y no hay soporte para @slot en roxygen:
¿Es esto cierto para roxygen2? La publicación mencionada anteriormente sugiere que un usuario debería hacer su propia lista detallada con el marcado LaTeX. Por ejemplo, una nueva clase S4 que extiende la clase "character" 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, esto \describe , \item el enfoque para documentar las ranuras parece inconsistente con el resto de roxygen (2), ya que no hay etiquetas @ delimitadas y las ranuras podrían ir indocumentado sin objeción de roxygenize(). Tampoco dice nada sobre una forma consistente de documentar la herencia de la clase que se está definiendo. Imagino que la dependencia todavía funciona generalmente bien (si una ranura en particular requiere una clase no base de otro paquete) usando la etiqueta @import.
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:{[13]]}
- Una lista It detallada (como ejemplo arriba).
- B {
@slot... pero con etiquetas adicionales/implementación me perdí. No pude conseguir @slot para trabajar con roxygen / roxygen2 en versiones donde se incluyó como un reemplazo para la lista detallada en el ejemplo arriba. De nuevo, el ejemplo anterior funciona con roxygen(2).- C Some Alguna etiqueta alternativa para especificar ranuras, como
@param, que lograría lo mismo.
Estoy tomando prestada / extendiendo esta pregunta de un post que hice a la página de desarrollo de roxygen2 en github.
3 answers
Respuesta actualizada para Roxygen2 5.0.1, actual a partir de 6.0.1
Para S4, la mejor práctica ahora es documentar usando la etiqueta @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
En una nota lateral, @exportClass solo es necesario en algunos casos, la forma general de exportar una función es usar @export ahora. Tampoco tiene que exportar una clase, a menos que desee que otros paquetes puedan extender la clase.
Véase también http://r-pkgs.had.co.nz/namespace.html#exports
Respuesta Actualizada para Roygen2 3.0.0, actual a partir de 5.0.1.
Para S4, la mejor práctica es la documentación en la forma:
#' \section{Slots}{
#' \describe{
#' \item{\code{a}:}{Object of class \code{"numeric"}.}
#' \item{\code{b}:}{Object of class \code{"character"}.}
#' }
#' }
Esto es consistente con la representación interna de 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 robusta en el futuro que incorpore el conocimiento de la herencia but pero hoy eso no existe.
Como señaló @Brian Diggs, esta característica se introdujo en 3.0.0, además discusión en https://github.com/klutometis/roxygen/pull/85
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-03-28 16:04:55
La solución proporcionada por Full Decent está bien si va a documentar ranuras en los propios archivos de escritorio Remoto. Al usar roxygen2, puedes usar la etiqueta @section para 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
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2013-01-09 13:49:10
Roxygen2 v4. 1+ y el último documento de Hadley para hacer esto:
Http://r-pkgs.had.co.nz/man.html#man-classes
Todavía no lo he probado para RC, pero ahora funciona para mí para S4.
Anteriormente
Parece que las ranuras de clase S4 son totalmente compatibles con Roxygen2 versión 3.0+:
Http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0 /
" documente sus clases S4, métodos S4 y clases RC con roxygen2 – puede eliminar de forma segura soluciones alternativas que utilizan @alias y @usage, y simplemente confían en roxygen2 para hacer lo correcto."
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2015-08-06 18:13:36