Multiple functions in one .Rd file

Solution 1:

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.

Solution 2:

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.