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

Question

Tengo dos métodos para un genérico S3 (definidos en otro paquete) que están estrechamente relacionados, así que quería documentarlos en el mismo archivo Rd. Sin embargo, cuando se documentan sus argumentos por separado, recibo una advertencia de R CMD check sobre "entradas argumento duplicado en \ 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 la define genéricos. 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 vinculados, por lo 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 mantener todo junto, como es el punto de Roxygen.

¿Es posible obtener roxygen para crear un legal (sin duplicar el argumento) 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 S3 es que no debería ser necesario tener descripciones diferentes para el mismo argumento.

Es claro desde la sección de uso qué clases son aceptadas (para el argumento en el que se produce el envío), si se produce la documentación del método S3 con ##' @method y ##' @S3method. Para los otros argumentos, diría que necesitar descripciones diferentes probablemente sea un indicador de que se deben usar diferentes nombres de argumento.

Así que a partir de:

##' 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 
} 

consigo 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 argumentos necesitan diferentes descripciones, es aceptable para documentar los métodos por separado en archivos separados. Esta no es mi opinión, es cómo lo hacen en el código fuente R. Y si lo hacen, debe ser correcto. Mira las páginas de documentación para el paquete "estadísticas". Tenga en cuenta que hay archivos separados para prediction.arima, predict.gls, y así sucesivamente.

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

$ 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 la crítica anterior que sugiere que debe cambiar el nombre de los argumentos si necesitan diferentes descripciones. Esto subestima la idea de polimorfismo orientada a objetos, que nos anima a no proliferar nombres diferentes a menos que sea necesario.