più funzioni in un unico file .rd

Question

Breve versione: Posso emulare la documentazione dei Normal nel pacchetto stats utilizzando roxygen?

lungo versione: Sto lavorando su un pacchetto e stava cercando rendere la documentazione più leggibile di avere un certo numero di funzioni con ingressi comuni/parametri raccolti sotto lo stesso titolo, che sarà un riferimento generico al gruppo. Ogni funzione dovrebbe essere ancora disponibile per l'utente finale in modo indipendente.

Ho preso come ispirazione la documentazione per Normal che fornisce un numero di metodi relativi alla distribuzione normale, ad es. stats::dnorm().

Quando cerco ?dnorm trovo il nome della sezione di aiuto è Normal anche se Normal non sembra essere una funzione o di un oggetto esportato.

Quello che ho provato sta mettendo quanto segue in 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 

Ho poi corro roxygen2 di quanto sopra. Il problema è che quando si esegue R CMD check su questo pacchetto minimo, si trova che il pacchetto non può essere caricato come undefined exports: funs. Se rimuovo la riga ##' @name funs il pacchetto passa R CMD check ma il nome della sezione della guida è sum1 anziché funs. Se posso aggiungere il seguente sotto la sezione esempi:

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

Passa e posso vedere l'aiuto formattato come vorrei, ma sto esportare una funzione senza senso, al fine di ottenere il nome per visualizzare correttamente.

Ho provato a cercare nei file della guida di origine per stats per vedere come è stato ottenuto, ma sono nel formato .Rdx che non so come visualizzare.

Inoltre, su una nota correlata, che tipo di cosa èNormal?

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

---

Aggiornamento:

@TylerRinker - Ho paura che questa è stata la prima cosa che avevo provato. Questa combina le funzioni in un unico .Rd file, ma il nome della guida associata è lo stesso come il nome della prima funzione, che è quello che stavo cercando di evitare:

##' 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 - questa soluzione provoca esattamente la stessa difficoltà, il nome dell'aiuto è lo stesso della prima funzione.

Forse questo proprio non è possibile ...

Answer 1

Questa è la soluzione migliore che ho trovato, ma sarà lieto di cambiare risposta accettata se qualcosa di meglio arriva ...

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

Si noti che la formattazione evita l'uso di @usage al fine di evitare di fare questo a reportable bug.

Posso vedere come questo potrebbe essere stato meglio indirizzato su github.

Una soluzione migliore, che fa uso di @usage è quello di aggiungere la seguente riga:

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

dopo il primo uso di

##' @rdname funs 
##' @export 

Comunque sto cercando di ridurre al minimo il no. di avvertimenti lanciati da R CMD check per placare il potere costituito, in particolare, il folloiwng:

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. 

Quest'ultimo può essere un errore di mia lettura di documentazione per @usage.

Molte grazie.

Answer 2

Per quanto ho capito, l'unico modo per avere 3 nomi documentati nel tuo file .Rd è di documentare 3 oggetti reali come hai fatto tu. Ma il trucco è: uno di loro può essere NULL e non esportato!

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

Sembra abbastanza hacky, ma funziona.