r - queda - en excel una copia en conflicto

Conflicto de nombre de archivo Rd cuando se extiende un método S4 de algún otro paquete

Question

Pregunta real

¿Cómo evito los conflictos de nombre de archivo Rd cuando

1. un S4 genérico y su (s) método (s) no están necesariamente todos definidos en el mismo paquete (el paquete que contiene (algunos de) los métodos personalizados depende del paquete que contiene el genérico) y
2. usando roxygenize() del paquete roxygen2 para generar los archivos Rd reales?

No estoy seguro si esto es un problema roxygen2 o un problema común cuando el genérico y su (s) método (s) están dispersos a través de paquetes (que en mi humilde opinión es definitivamente un caso de uso realista si sigue un estilo de programación modular).

¿Cuál es la forma recomendada de manejar estas situaciones?

Ilustración

En el paquete pkga

Supongamos que en el paquete pkga definió un método genérico foo y que ha proporcionado el código roxygen respectivo que roxygenize() recoge para generar el archivo Rd:

#'' Test function
#'' 
#'' Test function.
#'' 
#'' @param ... Further arguments.
#'' @author Janko Thyson /email{janko.thyson@@rappster.de}
#'' @example inst/examples/foo.R
#'' @docType methods
#'' @rdname foo-methods
#'' @export

setGeneric(
    name="foo",
    signature=c("x"),
    def=function(
         x,  
        ...
    ) {
    standardGeneric("xFoo")       
    }
)

Cuando roxygenizing() su paquete, se crea un archivo llamado foo-methods.Rd en el subdirectorio man que sirve como el archivo Rd de referencia para todos los métodos que se pueden crear para este método genérico. Hasta aquí todo bien. Si todos los métodos para este genérico también son parte de su paquete, todo está bien. Por ejemplo, este código roxygen se aseguraría de que la documentación se agregue a foo-methods.Rd para el método ANY de foo :

#'' @param x /code{ANY}.
#'' @return /code{TRUE}.
#'' @rdname foo-methods
#'' @aliases foo,ANY-method
#'' @export

setMethod(
    f="foo", 
    signature=signature(x="ANY"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(TRUE)
    }, options=list(suppressAll=TRUE))
)

Sin embargo, si el paquete pkga proporciona el genérico para foo y usted decide en otro paquete (por ejemplo, pkgb ) agregar un foo método para que x sea ​​de character de clase, entonces la R CMD check le dirá que hay un choque de nombre con respecto a Nombres de archivo Rd y / o alias (ya que ya existe un archivo Rd foo-methods.Rd pkga en pkga ):

En paquete pkgb

#'' @param x /code{character}.
#'' @return /code{character}.
#'' @rdname foo-methods
#'' @aliases foo,character-method
#'' @export

setMethod(
    f="foo", 
    signature=signature(x="character"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(x)
    }, options=list(suppressAll=TRUE))
)

Para ser más precisos, este es el error que se produce / escribe en el archivo 00install.out

Error : Q:/pkgb/man/foo-methods.Rd: Sections /title, and /name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package ''pkgb''

Diligencia debida

Traté de cambiar los valores de @rdname y @aliases a foo_pkgb* (en lugar de foo* ), pero /title y /name aún están configurados en foo cuando se usa roxygenizing y, por lo tanto, el error persiste. ¿Alguna idea además de editar manualmente los archivos Rd generados por roxygenize() ?

EDITAR 2012-12-01

A la luz de comenzar la recompensa, la pregunta real podría obtener un sabor ligeramente más amplio:

¿Cómo podemos implementar algún tipo de verificación "entre paquetes" con respecto a los archivos Rd y / o cómo podemos consolidar los archivos de ayuda del método S4 dispersos a través de paquetes en un solo archivo Rd para presentar una única fuente de referencia para el final? -¿usuario?

Answer 1

La pregunta básica es de hecho "roxigenizar", solo. Es por eso que nunca había visto el problema.

Si bien hay buenas razones para el enfoque roxygenizing del desarrollo de paquetes, todavía veo una muy buena razón para no ir allí:

Súplica por roxygenación mucho menos extrema

Las páginas de ayuda resultantes tienden a parecer extremadamente aburridas, no solo los archivos generados automáticamente * .Rd sino también el resultado representado. P.ej

1. los ejemplos a menudo son mínimos, no contienen comentarios, a menudo no están bien formateados (usando espacio, / nuevas líneas / ...)
2. Los problemas matemáticos rara vez se explican a través de / eqn {} o / deqn {}
3. / describe {..} y el formato similar de nivel superior rara vez se usa

¿Porqué es eso? Porque

1) leer y editar los comentarios de roxygen es mucho más "engorroso" o al menos visualmente ingrato que leer y editar archivos * .Rd en ESS o Rstudio o (otro IDE que tenga integrado el soporte * .Rd)

2) Si se usa esa documentación

es lo que se genera automáticamente al final de la construcción / verificación de su paquete

Por lo general, tienden a no considerar la documentación R bien escrita como algo importante (sino más bien su código R, para lo cual todos los documentos son solo un comentario :-)

El resultado de todo eso: la gente prefiere escribir documentación sobre sus funciones en viñetas o incluso blogs, github, videos de youtube, o ... donde es muy agradable a la hora de la autoría, pero está bastante separado del código y atado desfasarse y marchitarse (y por lo tanto, a través de la búsqueda de Google engañar a sus usuarios) -> La motivación original de Roxygen de tener código y documentación en el mismo lugar es completamente derrotada.

Me gusta roxygen y lo uso extensivamente en el momento en que creo una nueva función ... y la conservo y mantengo siempre que mi función no esté en un paquete o no se exporte. Una vez que decido exportarlo, ejecuto (el equivalente a ESS de) roxygenize () una vez y de ahí en adelante tomo la pequeña carga adicional de mantener un archivo * .Rd que está bien formateado, contiene sus propios comentarios (para mí como autor) , tiene muchos buenos ejemplos, tiene su propio historial de control de revisión (git / svn / ...), etc.

Answer 2

Logré generar archivos NAMESPACE y * .Rd para los métodos S4 para genéricos definidos en otro paquete que el mío.

Me llevó los siguientes pasos:

1. Crear NAMESPACE a mano como una solución a un error roxygen2 conocido .

   ¡Escribir un NAMESPACE a mano no es tan difícil!

   Desactiva la generación de NAMESPACE por roxygen2 en RStudio:

   Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.

2. importe el paquete que contiene el genérico y exporte los métodos S4 utilizando exportMethods .

3. Escriba documentación roxygen2 por separado para cada uno de los métodos S4. No combine la documentación de roxygen2 (como generalmente hago para diferentes métodos del mismo genérico).

4. Agregue etiquetas roxygen explícitas @title y @description a la documentación roxygen de los métodos S4. Escriba @description explícitamente, incluso si su valor es idéntico a @title.

Eso hace que funcione para mí.