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