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 @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 no hay soporte para @slotroxygen:

¿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, \itemmé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 @importetiqueta.

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 roxygen2página de desarrollo en github .

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 @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

En una nota al margen, @exportClasssolo es necesario en algunos casos, la forma general de exportar una función es usar @exportahora. Tampoco tiene que exportar una clase, a menos que desee que otros paquetes puedan extender la clase.

Ver 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 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 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 3.0.0, más discusión en https://github.com/klutometis/roxygen/pull/85

La solución proporcionada por Full Decent está bien si va a documentar ranuras en los propios 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

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 me funciona para S4.

Previamente

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 las soluciones alternativas que utilizó @aliasy @usage, y simplemente confiar en roxygen2 para hacer lo correcto".