example - Documentar dos métodos S3 en el mismo archivo con Roxygen

roxygen2 documentation data

Question

Tengo dos métodos para un S3 genérico (definido en otro paquete) que están estrechamente relacionados y, por lo tanto, quería documentarlos en el mismo archivo Rd . Sin embargo, cuando documento sus argumentos por separado, recibo una advertencia de R CMD check sobre "Duplicado / entradas de argumento en el objeto de documentación"

##'' Create a ggplot of a Kaplan-Meier Survival curve(s)
##''
##'' @param data A /code{survfit} object returned from /code{/link{survfit}}
##'' @param /dots Unused
##'' @return A ggplot2 object
autoplot.survfit <- function(data, ...) {
NULL
}
##'' @rdname autoplot.survfit
##'' @param data A /code{/link{survfit.fortify}} object returned from /code{/link{fortify.survfit}}
autoplot.survfit.fortify <- function(data, ...) {
NULL
}

El primer argumento debe ser data porque eso es lo que define el genérico. Sin embargo, la documentación para ello es diferente para los diferentes métodos, aunque solo sea porque debe ser de una clase diferente. Podría tener dos archivos de documentación separados para esto, pero están estrechamente relacionados, así que me gustaría mantenerlos juntos. Podría enumerar todas las clases posibles de data en la primera invocación y no tener nada en las siguientes, pero eso significa que estoy documentando la segunda función con la primera en lugar de mantenerla todo junto como es el punto de Roxygen.

¿Es posible obtener roxygen para crear un legal (sin duplicar el argumento) a partir de múltiples métodos? Si no, ¿cuál es la mejor manera de manejar este escenario?

Answer 1

Creo que la idea detrás de los métodos genéricos de S3 es que no debería ser necesario tener diferentes descripciones para el mismo argumento.

De la sección de uso se desprende claramente qué clases se aceptan (para el argumento sobre el cual se realiza el envío), si produce la documentación del método S3 con ##'' @method y ##'' @S3method . Para los otros argumentos, diría que la necesidad de descripciones diferentes es probablemente un indicador de que se deben usar nombres de argumentos diferentes.

Así que desde

##'' Create a ggplot of a Kaplan-Meier Survival curve(s)
##''
##'' @param data the object to be plotted
##'' @param /dots Unused
##'' @method autoplot survfit
##'' @S3method autoplot survfit
##'' @return A ggplot2 object
autoplot.survfit <- function(data, ...) {
NULL
}
##'' @rdname autoplot.survfit
##'' @method autoplot survfit.fortify
##'' @S3method autoplot survfit.fortify
autoplot.survfit.fortify <- function(data, ...) {
NULL
}

Me sale con roxygen2

Create a ggplot of a Kaplan-Meier Survival curve(s)
Description:
Create a ggplot of a Kaplan-Meier Survival curve(s)
Usage:
## S3 method for class ''survfit''
autoplot(data, ...)
## S3 method for class ''survfit.fortify''
autoplot(data, ...)
Arguments:
data: the object to be plotted
...: Unused
Value:
A ggplot2 object

Answer 2

Si los nombres de los argumentos necesitan descripciones diferentes, es aceptable documentar los métodos separados en archivos separados. Esta no es mi opinión, es cómo lo hacen en el código fuente de R. Y si lo hacen, debe ser correcto. Mira las páginas de documentación para el paquete "stats". Tenga en cuenta que hay archivos separados para predict.arima, predict.gls, etc.

En la fuente R, hay varios archivos diferentes para los métodos de impresión. Observar:

$ find . -name "print*.Rd"
./base/man/print.Rd
./base/man/print.dataframe.Rd
./base/man/print.default.Rd
./stats/man/print.power.htest.Rd
./stats/man/printCoefmat.Rd
./stats/man/print.ts.Rd
./tools/man/print.via.format.Rd`

No estoy de acuerdo con el póster anterior que sugirió que debería cambiar el nombre de los argumentos si necesitan descripciones diferentes. Eso recorta la idea del polimorfismo orientada a objetos, que nos anima a no proliferar nombres diferentes a menos que sea necesario.