55

短版：我可以使用Normal包中的文档来模拟吗？statsroxygen

长版：我正在开发一个包，并试图通过在一个标题下收集许多具有通用输入/参数的函数来使文档更具可读性，这将是对该组的通用引用。每个功能仍应可供最终用户独立使用。

我以文档为灵感，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 - 这个解决方案导致完全相同的困难，帮助的名称与第一个函数相同。

也许这只是不可能的......

4

2 回答 2

26

这是我找到的最好的解决方法，但如果出现更好的答案，我会很高兴改变接受的答案......

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

非常感谢。

于 2013-04-14T06:01:08.343 回答
25

据我了解，在 .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

它看起来很hacky，但它确实有效。

于 2013-12-02T22:15:23.720 回答