¿Cómo documentar correctamente los espacios de clase S4 usando Roxygen2?

Question

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, actual o planificada, para documentar las clases S4 en roxygen2?

Debida diligencia:

Encontré una mención de una etiqueta @slot 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 en roxygen:

¿Es esto cierto de roxygen2? La publicación mencionada anteriormente sugiere que un usuario debería crear su propia lista detallada con el marcado LaTeX. P.ej. una nueva clase S4 que amplía la clase "character" 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 enfoque \describe, \item para documentar las ranuras parece inconsistente con el resto de roxygen (2), ya que no hay etiquetas delimitadas por @ y las ranuras podrían quedar sin documentar sin objeción de roxygenize(). Tampoco dice nada sobre una forma coherente de documentar la herencia de la clase que se está definiendo. Imagino que la dependencia todavía funciona 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 tragamonedas roxygen (2)?

Parece que hay 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 donde se incluyó como reemplazo de la lista detallada en el ejemplo encima. 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 página de desarrollo de roxygen2 en github .

Answer 1

roxygen2 v4.1 + y el último documento de Hadley para hacer esto:

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

Todavía no lo he probado para RC, pero ahora me funciona 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 manera segura las soluciones que usaban @alias y @usage, y simplemente confíe en roxygen2 para hacer lo correcto".

Answer 2

Respuesta actualizada para Roxygen2 5.0.1, actual a partir de 6.0.1

Para S4, la mejor práctica ahora es documentar utilizando 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 al margen, @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.

Consulte también http://r-pkgs.had.co.nz/ namespace.html # exportaciones

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 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 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 función se incorporó a la versión 3.0.0; se puede consultar más información en https://github.com/klutometis/roxygen/pull/85

Answer 3

La solución proporcionada por Full Decent está bien si opta por documentar espacios en los archivos Rd.Cuando use roxygen2, puede 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