class - data - roxygen template
¿Cómo documentar correctamente las ranuras de clase S4 utilizando Roxygen2? (3)
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í con S4.
Previamente
Parece que las ranuras de clase S4 son totalmente compatibles con la versión 3.0+ de Roxygen2:
http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/
"documente sus clases de S4, métodos de S4 y clases de RC con roxygen2; puede eliminar de forma segura las soluciones que usaron @alias y @usage , y simplemente confíe en roxygen2 para hacer lo correcto".
Para documentar clases con roxygen (2), especificar un título y una descripción / detalles parece ser el mismo que para funciones, métodos, datos, etc. Sin embargo, los espacios y la herencia son su propio tipo de animal. ¿Cuál es la mejor práctica, actual o planificada, para documentar las clases de S4 en roxygen2?
Debida diligencia:
Encontré la mención de una etiqueta @slot en las primeras descripciones de roxygen. Una publicación de la lista de correo de R-forge 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 debe hacer su propia lista detallada con el marcado LaTeX. Por ejemplo, una nueva clase S4 que amplíe la clase de "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 de /describe , /item para documentar las ranuras parece ser inconsistente con el resto de roxygen (2), ya que no hay etiquetas delimitadas por @ y las ranuras podrían no estar documentadas sin objeción 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 básica 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:
- A - Lista detallada (como ejemplo anterior).
- B -
@slot... pero con etiquetas / implementación extra me perdí. No pude conseguir que @slot funcione con roxygen / roxygen2 en versiones en las que se incluyó como un reemplazo para la lista detallada en el ejemplo anterior. De nuevo, el ejemplo anterior funciona con roxygen (2).- C - Alguna etiqueta alternativa para especificar ranuras, como
@param, que lograría lo mismo.
Estoy tomando prestado / extendiendo esta pregunta de una publicación que hice en la página de desarrollo de github en github .
La solución provista por Full Decent está bien si va a documentar las ranuras 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
Respuesta actualizada para Roxygen2 5.0.1, vigente 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 @exportClass 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#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 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 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 robusta en el futuro que incorpore el conocimiento de la herencia, pero hoy en día eso no existe.
Como lo señaló @Brian Diggs, esta función se incorporó a 3.0.0, una discusión más detallada en github.com/klutometis/roxygen/pull/85