Fonctions multiples dans un fichier .Rd

Version courte : Puis-je émuler la documentation de Normal dans les stats package en utilisant roxygen ?

Version longue : Je travaille sur un paquet et essayais de rendre la documentation plus lisible en ayant un certain nombre de fonctions avec des entrées / parameters communs collectés sous un seul titre, ce qui sera une référence générique au groupe. Chaque fonction doit toujours être disponible pour l’utilisateur final indépendamment.

J’ai pris comme source d’inspiration la documentation de Normal qui donne un certain nombre de méthodes liées à la dissortingbution normale, par exemple, stats::dnorm() .

Lorsque je recherche ?dnorm je trouve que le nom de la section d’aide est Normal même si Normal ne semble pas être une fonction ou un object exporté.

Ce que j’ai essayé est de mettre les funs.R suivantes dans l’ 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 

Je lance alors roxygen2 sur ce qui précède. La difficulté est que lors de l’exécution de la R CMD check sur ce package minimal, il est impossible de charger le package en tant undefined exports: funs . Si je supprime la ligne ##' @name funs le package réussit la R CMD check mais le nom de la section d’aide est sum1 plutôt que funs . Si j’ajoute ci-dessous la section des exemples:

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

Il passe et je peux voir l’aide formatée comme je le souhaite, mais j’exporte une fonction sans signification pour que le nom s’affiche correctement.

J’ai essayé de chercher dans les fichiers d’aide source des stats pour voir comment cela était réalisé, mais elles sont au format .Rdx et je ne sais pas comment les afficher.

En outre, sur une note connexe, est-ce que ce genre de chose est Normal ?

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

Mettre à jour:

@TylerRinker – J’ai peur que ce soit la première chose que j’ai essayée. Cela combine les fonctions en un .Rd fichier .Rd mais le nom de l’aide associée est le même que le nom de la première fonction, ce que j’essayais d’éviter:

 ##' 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 – cette solution pose exactement la même difficulté, le nom de l’aide est le même que la première fonction.

Peut-être que ce n’est pas possible …

C’est la meilleure solution de contournement que j’ai trouvée, mais je serai ravi de changer la réponse acceptée si quelque chose de mieux se présente …

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

Notez que le formatage évite l'utilisation de @usage pour éviter d'en faire un bogue à signaler .

Je peux voir comment cela a pu être mieux abordé sur github .

Une meilleure solution qui utilise @usage est d'append la ligne suivante:

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

après la première utilisation de

 ##' @rdname funs ##' @export 

Cependant, j'essaie de minimiser le non. des avertissements lancés par R CMD check afin de calmer les pouvoirs, en particulier les suivants:

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

Ce dernier peut être une erreur de lecture de la documentation de @usage .

Merci beaucoup.

Pour autant que je sache, la seule façon d’avoir 3 noms documentés dans votre fichier .Rd est de documenter 3 objects réels comme vous l’avez fait. Mais l’astuce est que l’un d’entre eux peut être NULL et non exporté!

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

Ça a l'air plutôt pirate, mais ça marche.