Multiple functions in one .Rd file

Question

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...

Answer 1

As far as I understand, the only way to have 3 names documented in your .Rd file is to document 3 actual objects as you did. But the trick is: one of them can be NULL and not exported!

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

It looks quite hacky, but it works.

Answer 2

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.