一个.Rd文件中有多个函数

Question

简短版：我能使用roxygen模拟stats包中Normal的文档吗？

详细版：我正在开发一个包，并试图通过将具有共同输入/参数的多个函数收集在一个标题下，使文档更易读，这将是对该组的通用引用。每个函数仍应独立地提供给最终用户。

我以Normal的文档为灵感，其中提供了许多与正态分布相关的方法，例如stats::dnorm()。

当我搜索?dnorm时，我发现帮助部分的名称为Normal，即使Normal似乎不是导出的函数或对象也是如此。

我尝试将以下内容放入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

接下来我在上述代码上运行roxygen2。

问题在于，当在此最小化的包上运行R CMD check时，它会发现该包无法加载，因为undefined exports: funs。

如果我删除##' @name funs这一行，则包通过R CMD check，但帮助部分的名称将是sum1而不是funs。

如果我在示例部分下添加以下内容：

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

它通过了，我可以看到帮助文本以我想要的方式格式化，但是为了正确显示名称，我导出了一个无意义的函数。

我试图查看stats的源帮助文件，以了解如何实现它，但它们以.Rdx格式编写，我不确定如何显示。

另外，关于相关问题，Normal是什么类型的事物？

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

---

更新：

@TylerRinker - 恐怕这是我尝试的第一件事情。 这将函数合并为一个.Rd文件，但相关帮助的名称与第一个函数的名称相同，而这正是我试图避免的：

##' 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 - 这个解决方案会导致完全相同的困难，帮助的名称与第一个函数的名称相同。

也许这根本不可能......

- dardisco

---

我可能错了，但这是我处理它的方式：https://github.com/trinker/reports/blob/master/R/GQ.R - Tyler Rinker

删除 ##' @name funs，然后它应该可以工作（我想）。 - Andrie

从Hadley的相关帖子中，涉及到@describeIn选项的使用。 - zx8754

未来的谷歌用户请注意：请查看 https://gist.github.com/jefferys/b79fe87314b0dc72fec9 - Ricardo Saporta

Answer 1

据我所了解，在您的.Rd文件中记录3个名称的唯一方法是记录3个实际对象，就像您所做的那样。但诀窍是：其中一个可以是NULL并且未导出！

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

看起来很粗糙，但它能正常工作。

- Calimo

Answer 2

这是我找到的最佳解决方法，但如果有更好的方法出现，我很乐意更改接受的答案...

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

请注意，格式化避免使用@usage，以避免使其成为可报告的错误。

我可以看出这个问题可能更好地在github上得到解决。

一个更好的解决方案是使用@usage添加以下行：

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

第一次使用后

##' @rdname funs
##' @export

然而，我正在尽力减少 R CMD check 抛出的警告数量，以取悦管理层，特别是以下内容：

 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.

这可能是我对@usage文档阅读的错误。

非常感谢。

- dardisco

---

我认为你不需要@aliases，这些将通过@rdname funs自动添加。其次，@usage必须仅包含R代码，因此如果要添加注释，请在注释“##' @usage funs(x,y) # A nominal function of x and y”之后添加。 - Calimo

我知道这对函数是如何工作的。如何修改它来适用于数据集呢？ - jebyrnes

@jebyrnes，我发现对于数据集，我唯一遇到的问题是仅考虑第一个 "@format"。 - Ferroao