Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Multiple functions in one .Rd file

Short version: Can I emulate the documentation of Normal in package stats using roxygen?

Long version: I'm working on a package and was trying make the documentation more readable by having a number of functions with common inputs/parameters collected under one heading, which will be a generic reference to the group. Each function should still be available to the end user independently.

I took as inspiration the documentation for Normal which gives a number of methods related to the normal distribution e.g. stats::dnorm().

When I search ?dnorm I find the name of the help section is Normal even though Normal does not appear to be an exported function or object.

What I've tried is putting the following into 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 

I then run roxygen2 on the above. The difficulty is that when running R CMD check on this minimal package, it finds the package cannot be loaded as undefined exports: funs. If I remove the line ##' @name funs the package passes R CMD check but the name of the help section is sum1 rather than funs. If I add the following below the examples section:

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

It passes and I can see the help formatted as I would like, but I'm exporting a meaningless function in order to get the name to display correctly.

I tried looking in the source help files for stats to see how it was achieved, but they are in .Rdx format which I'm not sure how to display.

Also, on a related note, does what sort of thing is Normal?

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

Update:

@TylerRinker - I'm afraid this was the first thing I had tried. This combines the functions into one .Rd file but the name of the associated help is the same as the name of the first function, which is what I was trying to avoid:

##' 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 - this solution causes exactly the same difficulty, the name of the help is the same as the first function.

Perhaps this just isn't possible...

like image 782
dardisco Avatar asked Apr 10 '13 17:04

dardisco


People also ask

How do you add multiple functions in R?

The lapply () and sapply () functions can be used for performing multiple functions on a list in R. This function is used in order to avoid the usage of loops in R. The difference between both the functions is the sapply () function does the same job as lapply () function but returns a vector.

What is an .RD file?

R objects are documented in files written in “R documentation” (Rd) format, a simple markup language much of which closely resembles (La)TeX, which can be processed into a variety of formats, including LaTeX, HTML and plain text.


1 Answers

This is the best workaround I've found, but will be glad to change accepted answer if something better comes along...

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

Note that formatting avoids the use of @usage in order to avoid making this a reportable bug.

I can see how this may have been better addressed on github.

A better solution which does use @usage is to add the following line:

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

after the first use of

##' @rdname funs ##' @export 

However I'm trying to minimize the no. of warnings thrown by R CMD check in order to placate the powers that be, in particular the 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. 

This last may be an error of my reading of documentation for @usage.

Many thanks.

like image 93
dardisco Avatar answered Sep 20 '22 10:09

dardisco