example - Múltiples funciones en un archivo.Rd

roxygen2 documentation data

Question

Versión corta : ¿Puedo emular la documentación de Normal en las stats paquete usando roxygen ?

Versión larga : estoy trabajando en un paquete e intento hacer que la documentación sea más legible teniendo varias funciones con entradas / parámetros comunes recogidos bajo un encabezado, que será una referencia genérica para el grupo. Cada función debería estar disponible para el usuario final de forma independiente.

Tomé como inspiración la documentación para Normal que proporciona una serie de métodos relacionados con la distribución normal, por ejemplo, stats::dnorm() .

Cuando busco ?dnorm encuentro que el nombre de la sección de ayuda es Normal aunque Normal no parece ser una función u objeto exportado.

Lo que he intentado es poner lo siguiente en funs.R :

##'' @rdname funs
##'' @name funs
##'' @aliases sum1
##'' @aliases prod1
##'' @title Two functions
##'' @param x X
##'' @param y Y
##'' @return sum1 returns x+y
##'' /cr
##'' prod1 returns x*y
##'' @examples
##'' sum1(3,4)
##'' prod1(3,4)
##'' @export
sum1 <- function(x,y) x+y
##'' @export
##'' @rdname funs
prod1 <- function(x,y) x*y

Luego corro roxygen2 en el anterior. La dificultad es que al ejecutar R CMD check este paquete mínimo y compruebe que el paquete no se puede cargar como undefined exports: funs . Si ##'' @name funs la línea ##'' @name funs el paquete pasa R CMD check pero el nombre de la sección de ayuda es sum1 lugar de funs . Si agrego lo siguiente debajo de la sección de ejemplos:

##'' @export
funs <- function(x) x

Pasa y puedo ver la ayuda formateada como me gustaría, pero estoy exportando una función sin sentido para que el nombre se muestre correctamente.

Traté de buscar en los archivos de ayuda de fuentes stats para ver cómo se logró, pero están en formato .Rdx , que no estoy seguro de cómo mostrar.

Además, en una nota relacionada, ¿qué tipo de cosa es Normal ?

require(stats)
getAnywhere("Normal")
> no object named ''Normal'' was found

Actualizar:

@TylerRinker - Me temo que esto fue lo primero que intenté. Esto combina las funciones en un .Rd archivo .Rd pero el nombre de la ayuda asociada es el mismo que el nombre de la primera función, que es lo que estaba intentando evitar:

##'' sum
##'' gives the sum
##'' @param x X
##'' @param y Y
##'' @return sum1 returns x+y
##'' @examples
##'' sum1(3,4)
##'' @rdname funs
##'' @export
sum1 <- function(x,y) x+y
##'' product
##'' gives the product
##'' @return prod1 returns x*y
##'' @examples
##'' prod1(3,4)
##'' @rdname funs
##'' @export
prod1 <- function(x,y) x*y

@Andrie: esta solución causa exactamente la misma dificultad, el nombre de la ayuda es el mismo que la primera función.

Quizás esto simplemente no es posible ...

Answer 1

Esta es la mejor solución que he encontrado, pero estaré encantado de cambiar la respuesta aceptada si llega algo mejor ...

##'' @name funs
##'' @aliases sum1
##'' @aliases prod1
##''
##'' @title Two functions of x and y
##''
##'' @param x =X
##'' @param y =Y
##''
##'' @note /code{funs} is a generic name for the functions documented.
##'' /cr
##'' If called, /code{funs} returns its own arguments.
##''
##'' @rdname funs
##'' @export
funs <- function(x,y) {identity(c(x,y))}
##''
##'' @rdname funs
##'' @return /code{sum1(x,y)} returns x+y
##'' @examples
##'' sum1(3,4)
##'' @export
sum1 <- function(x,y) x+y
##''
##'' @rdname funs
##'' @return /code{prod1(x,y)} returns x*y
##'' @examples
##'' prod1(3,4)
##'' @export
prod1 <- function(x,y) x*y

Tenga en cuenta que el formateo evita el uso de @usage para evitar que esto sea un error reportable .

Puedo ver cómo esto se pudo haber abordado mejor en github .

Una mejor solución que usa @usage es agregar la siguiente línea:

##'' @usage funs(x,y) A nominal function of x and y

después del primer uso de

##'' @rdname funs
##'' @export

Sin embargo, estoy tratando de minimizar el no. de las advertencias lanzadas por R CMD check para aplacar a los poderes fácticos, en particular el siguiente:

 Functions with /usage entries need to have the appropriate /alias
entries, and all their arguments documented.
The /usage entries must correspond to syntactically valid R code.

Esto último puede ser un error de mi lectura de la documentación de @usage .

Muchas gracias.

Answer 2

Por lo que yo entiendo, la única manera de tener 3 nombres documentados en su archivo .Rd es documentar 3 objetos reales como lo hizo. Pero el truco es: ¡uno de ellos puede ser NULL y no exportarse!

##'' @name funs
##'' @rdname funs
##''
##'' @title Two functions of sum1 and prod1
##''
##'' @param x =X
##'' @param y =Y
##''
##'' @return x*y (prod1) or x+y (sum1).
NULL
##'' @rdname funs
##'' @examples
##'' sum1(3,4)
##'' @export
sum1 <- function(x,y) x+y
##'' @rdname funs
##'' @examples
##'' prod1(3,4)
##'' @export
prod1 <- function(x,y) x*y

Se ve bastante hacky, pero funciona.