importfrom - r roxygen2 example

Cómo documentar adecuadamente los métodos S4 utilizando roxygen2

Question

He visto algunas discusiones en SO y otros lugares con respecto a cómo esto debería o se hará en futuras versiones de Roxygen2. Sin embargo, estoy atascado. ¿Cómo debo documentar un S4 genérico, así como sus métodos, usando Roxygen2? Un ejemplo de trabajo para un nuevo genérico / métodos, así como un ejemplo para extender genéricos de base S4 sería increíblemente útil. No quiero tener que hacer documentación separada (la mayoría) redundante para cada método S4 del mismo genérico.

Diligencia debida: he rastreado un ejemplo útil para el método "extraer". Sin embargo, parece estar desactualizado e incompleto para mi pregunta. Utiliza la etiqueta @slot en la documentación de la clase, que no es (¿ya no es?) Compatible. Solo muestra una extensión de un método S4 central "[", en lugar de un ejemplo completo de Roxygen que incluye la documentación del genérico S4.

¿Cómo documentar correctamente los métodos S4 "[" y "[<-" usando roxygen?

Si documenté completamente un nuevo S4 genérico con título, descripción @param @return @name @aliases @docType @rdname , y luego documenté el método S4 con solo el @name @aliases @docType @rdname , obtengo el siguiente R CMD check advertencia:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic ''plot'' and siglist ''myClass1,ANY'' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

Al principio, parecía que ninguno de mis métodos S4 documentados de esta manera con roxygen2 realmente había funcionado. Sin embargo, hasta ahora, he notado que mis extensiones del "mostrar" del método central no tienen un error asociado, a pesar de que fueron documentadas exactamente de la misma manera que el resto. Aquí hay un ejemplo de la documentación completa de roxygen que incluí en la parte superior de uno de los métodos de la demostración, que NO generó el error de documentación faltante:

#'' @name show
#'' @aliases show,myClass2-method
#'' @docType methods
#'' @rdname show-methods

Por lo tanto, estoy perdido. Como puede ver, he incluido la convención para alias para los métodos S4 descritos en la sección de documentación S4 del manual del paquete R , concretamente que los métodos deben tener un alias con el siguiente nombre (sin espacio):

generic,signature_list-method.

De alguna manera, esto no está siendo completamente entendido por R CMD check .

Finalmente, después de construir la documentación usando:

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

y construyendo el paquete, obtengo documentación funcional. Cualquier título de la documentación de un método específico termina en el campo ''Descripción'', bastante torpemente. Entonces, roxygen2 obviamente hizo algo con la documentación de cada método y está en el camino correcto. Sin embargo, no es suficiente para evitar una advertencia grande y preocupante de

> R CMD check mypkgname

Miré los archivos Rd, pero sé aún menos sobre ellos para ver rápidamente cuál es el problema, y ​​de todos modos quiero saber la solución roxygen2 para no tener que manipular los archivos Rd directamente después de cada revisión de la documentación.

Entonces esta es una pregunta multiparte:

1. ¿Cuál es el enfoque actual recomendado para la documentación del método S4 genérico y S4 con roxygen2?

2. ¿Hay algún buen ejemplo disponible en algún lugar que muestre los detalles completos?

3. ¿Cuál podría ser la causa y la solución de la advertencia de que falta la documentación para la mayoría de los métodos S4 (aunque los métodos con documentación "faltante" han tenido su documento procesado por roxygen2 y los archivos Rd resultantes son al menos lo suficientemente buenos para funcionar en el paquete después de R CMD build mypkgname )?

Answer 1

Soporte oficial, explicado en el documento de devtools

http://r-pkgs.had.co.nz/man.html#man-classes (desplácese hacia abajo a la subsección S4 ).

El breve ejemplo actual de esa página se reproduce a continuación (por conveniencia):

#'' An S4 class to represent a bank account.
#''
#'' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

El enlace anterior explica muy claramente el soporte de S3, S4 y RC a través de roxygen / devtools. Se debe considerar que la explicación reemplaza a la anterior, que funciona por ahora, pero es menos clara y más complicada.

La vieja respuesta

Aquí hay un ejemplo que debería funcionar para la mayoría de los métodos S4.

Para documentar los genéricos de S4, creo que las siguientes tres líneas son necesarias en la mayoría de mis encabezados genéricos:

#'' @export
#'' @docType methods
#'' @rdname helloworld-methods

Donde helloworld-methods se reemplaza con the_name_of_your_generic-methods . Este será el nombre del archivo Rd que contiene la documentación para el genérico y todos sus métodos. Esta convención de nomenclatura no es necesaria, pero es común y útil. La etiqueta @export es necesaria ahora que se necesita un espacio de nombres para su paquete y desea que este método esté disponible para los usuarios de su paquete, no solo para otros métodos / funciones en su paquete.

Para documentar los métodos, encuentro que solo se necesitan 2 líneas, proporcionando la etiqueta @rdname y @aliases . La instrucción @rdname debe coincidir exactamente con la del genérico. La etiqueta @aliases debe cumplir con una convención de nomenclatura descrita en la sección de documentación oficial S4 de Writing R Extensions .

#'' @rdname helloworld-methods
#'' @aliases helloworld,character,ANY-method

No debe haber espacios después de las comas en el nombre de @aliases . No sé las reglas exactas que rodean cuándo agregar ,ANY al final de la lista de firmas. El patrón parece ser que el número de elementos en todas las listas de firmas de @aliases debe coincidir con el número de elementos en el vector de firma más largo entre los métodos. En el ejemplo siguiente, uno de los métodos se define con la firma de 2 elementos, por lo que la R CMD check no se cumplió con la documentación a menos que ,ANY se haya agregado a la etiqueta de alias de los otros métodos, incluso si su definición de firma solo tiene un elemento

Un ejemplo completo sigue. Lo construí y funciona sin advertencias de nivel de documentación de R CMD check testpkg , utilizando un tenedor fijo de errores de una versión de desarrollo muy reciente de roxygen2 (que he puesto a disposición) . Para una instalación rápida de esta horquilla en su sistema, use la library("devtools"); install_github("roxygen", "joey711") library("devtools"); install_github("roxygen", "joey711") . La versión más reciente de roxygen2 no funcionará en este momento debido a un error de cotización (descrito en una respuesta separada), pero espero que esto se incorpore muy pronto y mi fork no será necesario. Para ver este ejemplo en el contexto del resto de un paquete y ver los archivos de documentación resultante (Rd), lo he puesto a disposición como un paquete de prueba trivial en github llamado testpkg .

##############################################################
#'' The title, in this case: Helloworld-ify the argument.
#''
#'' Some additional details about this S4 generic and its methods.
#'' The extra blank line between this section and the title is
#'' critical for roxygen2 to differentiate the title from the
#'' description section.
#''
#'' @param x Description of /code{x}. The main argument in this
#''  example. Most often has such and such properties.
#''
#'' @param y Description of /code{y}. An argument that is rarely
#''  used by /code{"helloworld"} methods. 
#''
#'' @param ... Additional argument list that might not ever
#''  be used.
#''
#'' @return A helloworld-ified argument. Oh, you''ll see.
#'' 
#'' @seealso /code{/link{print}} and /code{/link{cat}}
#'' 
#'' @export
#'' @docType methods
#'' @rdname helloworld-methods
#''
#'' @examples
#'' helloworld("thisismystring")
#'' helloworld(char2helloworld("thisismystring"))
#'' helloworld(matrix(0,3,3))
#'' helloworld(list(0,0,0))
#'' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
    cat("Hello World!")
    cat("/n")
    standardGeneric("helloworld")
})

#'' @rdname helloworld-methods
#'' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
    cat(class(x))
})

#'' @rdname helloworld-methods
#'' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
    show(x)
})

#'' @rdname helloworld-methods
#'' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
    show(x)
})

Este ejemplo asume que no necesita documentación específica de un método diferente porque sus métodos no han desviado violentamente del comportamiento que uno esperaría basado en el documento genérico. Hay medios en roxygen2 para manejar ese caso alternativo utilizando la etiqueta @usage , pero los detalles se manejarían mejor con una pregunta SO separada.

Entonces, la mayor parte de su esfuerzo de documentación va al encabezado roxygen por encima de la definición genérica. Esto tiene alguna base en el código, ya que el genérico debe incluir todos los argumentos específicos que aparecen en cualquiera de los métodos definidos posteriormente. Tenga en cuenta que los argumentos que se manejan como parte de ... en la lista de argumentos no se incluyen y no deben documentarse específicamente, pero el ... mismo debe documentarse también por encima del genérico (consulte el ejemplo completo a continuación).

Para obtener más detalles sobre los conceptos básicos de las funciones de documentación, hay una wiki en progreso , la antigua viñeta de roxygen , así como el sitio de desarrollo de roxygen2 en github . También hay una pregunta SO sobre la documentación de R con Roxygen en general.

Answer 2

He localizado que la respuesta a la parte (3) - la documentación no tan perdida de los métodos S4 - se debe a que las comillas se agregan erróneamente alrededor de las etiquetas / alias cuando se utiliza la convención de nomenclatura S4; lo más probable es que se deba a un error resultante del manejo de texto de un alias que contiene una coma como parte de su nombre. Esto sigue siendo cierto de la última versión de roxygen2 en el momento de esta publicación. Acabo de publicar una descripción más detallada del error con un ejemplo reproducible en la página roxygen2 github:

https://github.com/klutometis/roxygen/issues/40

Brevemente,

#'' @aliases show,helloworld-method

se convierte

/alias{"show,helloworld-method"}

en el archivo Rd resultante. Al eliminar las citas, se elimina la advertencia de R CMD check y la documentación se genera y es funcional en ambos casos.

Creo que las partes (1) y (2) de esta pregunta (mejores prácticas, buenos ejemplos) siguen abiertas.