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

Question

He visto algunas discusiones en SO y otros lugares sobre cómo debería hacerse o se hará esto en futuras versiones de Roxygen2.Sin embargo, estoy estancado.¿Cómo debo documentar un S4 genérico, así como sus métodos, utilizando Roxygen2?Sería increíblemente útil un ejemplo práctico para un nuevo genérico/métodos, así como un ejemplo para ampliar el genérico base S4.No quiero tener que crear documentación separada (en su mayoría) redundante para cada método S4 del mismo genérico.

Debida diligencia:He localizado un ejemplo útil para el método de "extracción".Sin embargo, parece estar desactualizado e incompleto para mi pregunta.Utiliza la etiqueta @slot en la documentación de la clase, que no es compatible (¿ya no?).Solo muestra una extensión de un método central de S4 "[", 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 documento completamente un nuevo S4 genérico con título y descripción @param @return @name @aliases @docType @rdname, y luego documente el método S4 con solo el correspondiente @name @aliases @docType @rdname, me sale lo 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 había funcionado realmente.Sin embargo, hasta ahora, he notado que mis extensiones del método principal "mostrar" 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í arriba de uno de los métodos de presentació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 descrita en la sección de documentación S4 del manual del paquete R, es decir, que los métodos deben tener un alias con el siguiente nombre (sin espacios):

generic,signature_list-method.

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

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

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

y al construir 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', de manera bastante incómoda.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 amplia y preocupante por parte de

> R CMD check mypkgname

He examinado los archivos Rd, pero sé aún menos sobre ellos para ver rápidamente cuál es el problema y, de todos modos, quiero conocer la solución de 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 de varias partes:

1. ¿Cuál es el enfoque recomendado actualmente para la documentación genérica de S4 y del método 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 a la advertencia de que falta documentación para la mayoría de los métodos S4 (aunque los métodos con documentación "faltante" en realidad han tenido su documento analizado por roxygen2 y los archivos Rd resultantes son al menos lo suficientemente buenos para funcionar? en el paquete después R CMD build mypkgname) ?

Answer 1

Soporte oficial, explicado en el documento devtools

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

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 allí reemplaza la respuesta anterior a continuación, 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, encuentro necesarias las siguientes tres líneas en la mayoría de mis encabezados genéricos:

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

Dónde helloworld-methods se reemplaza con the_name_of_your_generic-methods.Este será el nombre del archivo Rd que contiene la documentación del genérico y todos sus métodos.Esta convención de nomenclatura no es obligatoria, pero es común y útil.El @export La etiqueta es necesaria ahora que se requiere 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 de su paquete.

Para documentar métodos, encuentro que solo son necesarias 2 líneas, proporcionando la @rdname y @aliases etiqueta.El @rdname La declaración debe coincidir exactamente con la del genérico.El @aliases La etiqueta debe cumplir con una convención de nomenclatura descrita en la sección de documentación oficial de S4 de Escribir extensiones R.

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

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

A continuación se muestra un ejemplo completo.Construí esto y funciona sin advertencias a nivel de documentación de R CMD check testpkg, usando un Bifurcación corregida 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 bifurcación en su sistema, use 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 se incorpore muy pronto y mi bifurcación no sea necesaria.Para ver este ejemplo en el contexto del resto de un paquete y ver los archivos de documentación resultantes (Rd), lo puse a disposición como un paquete de prueba trivial en github llamado paquete de prueba.

##############################################################
#' 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 supone que no necesita documentación separada específica del método porque sus métodos no se han desviado mucho del comportamiento que uno esperaría según el documento genérico.Hay medios en roxygen2 para manejar ese caso alternativo usando el @usage etiqueta, pero los detalles se manejarían mejor con una pregunta SO separada.

Entonces, la mayor parte de su esfuerzo de documentación se destina al encabezado de roxygen encima de la definición genérica.Esto tiene cierta 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 del ... en la lista de argumentos no están incluidos y no deben documentarse específicamente, pero los ... en sí también debe documentarse 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, existe una wiki en progreso, el vieja viñeta de roxygen, así como el sitio de desarrollo roxygen2 en github.También hay una SO pregunta sobre la documentación de R con Roxygen en general.

Answer 2

He descubierto que la respuesta a la parte (3), la documentación no tan faltante de los métodos S4, se debe a que se agregaron comillas erróneamente alrededor de las etiquetas \alias cuando se usa la convención de nomenclatura S4;Lo más probable es que se trate de un error resultante del manejo de texto de un alias que contiene una coma como parte de su nombre.Esto sigue siendo cierto para la última versión de roxygen2 en el momento de esta publicación.Acabo de publicar una descripción más completa del error con un ejemplo reproducible en la página de 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 comillas se elimina la R CMD check advertencia, y la documentación se compila y es funcional en ambos casos.

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