Question

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

长版本：我正在开发一个软件包，并试图通过在一个标题下收集一些具有公共输入/参数的函数来使文档更具可读性，这将是一个通用参考到小组。每个功能仍应独立地供最终用户使用。

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

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

Answer 1

这是我发现的最好的解决方法，但如果有更好的事情可以改变已接受的答案......

##' @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以避免使用此a reportable bug。

我可以看到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文档的错误。

非常感谢。

Answer 2

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

它看起来很黑，但它确实有用。

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

2 个答案: