多个功能在一个.Rd文件中 [英] Multiple functions in one .Rd file

问题描述

简短版本：可以在包 stats 中使用正常 roxygen ？

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.

我以正常的文档为灵感，它提供了许多与正态分布有关的方法。 统计:: dnorm（）。

I took as inspiration the documentation for Normal which gives a number of methods related to the normal distribution e.g. stats::dnorm().

当我搜索？dnorm 我发现帮助部分的名称是 / code>即使正常似乎不是导出的函数或对象。

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.

尝试将以下内容放入 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检查时，发现该包无法加载为 undefined exports：funs 。
如果我删除行 ##'@name funs 该包通过 R CMD检查，但名称帮助部分是 sum1 而不是 funs 。
如果在示例部分中添加以下内容：

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.

我尝试查找 stats 的源帮助文件，看看它是如何实现的， code> .Rdx 格式，我不知道如何显示。

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

---

更新：

@TylerRinker - 恐怕这是我尝试过的第一件事。这将功能组合成一个 .Rd 文件，但相关帮助的名称与第一个函数的名称相同，这是我试图避免的： / p>

@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 - 这个解决方案造成完全一样的困难，帮助的名称与第一个功能相同。

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

推荐答案

这是我找到的最好的解决方法，但很高兴更改接受的答案，如果有的话更好的来了...

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

请注意，格式化避免使用 @usage ，以避免使这个可报告错误。

Note that formatting avoids the use of @usage in order to avoid making this a reportable bug.

我可以看到如何更好地解决 github 。

I can see how this may have been better addressed on github.

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

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

但是我试图最小化不，由 R CMD检查抛出的警告，以安抚权力，特别是folloiwng：

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.

最后一次可能是我阅读 @usage 。

This last may be an error of my reading of documentation for @usage.

非常感谢。

这篇关于多个功能在一个.Rd文件中的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！