23

我有两种密切相关的 S3 泛型（在另一个包中定义）方法，因此我想将它们记录在同一个Rd文件中。R CMD check但是，当我分别记录他们的论点时，我从“文档对象中的重复 \argument 条目”中收到警告

##' Create a ggplot of a Kaplan-Meier Survival curve(s)
##'
##' @param data  A \code{survfit} object returned from \code{\link{survfit}}
##' @param \dots Unused
##' @return A ggplot2 object
autoplot.survfit <- function(data, ...) {
    NULL
}

##' @rdname autoplot.survfit
##' @param data A \code{\link{survfit.fortify}} object returned from \code{\link{fortify.survfit}}
autoplot.survfit.fortify <- function(data, ...) {
    NULL
}

第一个参数必须是data因为这是泛型定义的。但是，对于不同的方法，它的文档是不同的，只是因为它必须属于不同的类。我可以为此拥有两个单独的文档文件，但它们紧密耦合，因此我想将它们放在一起。我可以在第一次调用中列出所有可能的类，data而在随后的调用中没有任何内容，但这意味着我正在用第一个函数记录第二个函数，而不是像 Roxygen 那样将它们全部放在一起。

是否有可能让 roxygen 从多种方法中创建一个合法的（不重复参数）？如果没有，处理这种情况的最佳方法是什么？

4

2 回答 2

2

我认为 S3 泛型方法背后的想法是，不必对同一个参数有不同的描述。

##' @method如果您使用和生成 S3 方法文档，从使用部分可以清楚地看出哪些类被接受（对于发生分派的参数）##' @S3method。对于其他参数，我想说需要不同的描述可能表明应该使用不同的参数名称。

所以从：

##' Create a ggplot of a Kaplan-Meier Survival curve(s)
##'
##' @param data  the object to be plotted
##' @param \dots Unused
##' @method autoplot survfit
##' @S3method autoplot survfit
##' @return A ggplot2 object
autoplot.survfit <- function(data, ...) {
    NULL
}

##' @rdname autoplot.survfit
##' @method autoplot survfit.fortify
##' @S3method autoplot survfit.fortify
autoplot.survfit.fortify <- function(data, ...) {
    NULL
}

我和roxygen2

Create a ggplot of a Kaplan-Meier Survival curve(s)

Description:

Create a ggplot of a Kaplan-Meier Survival curve(s)

Usage:

     ## S3 method for class 'survfit'
      autoplot(data, ...)

     ## S3 method for class 'survfit.fortify'
      autoplot(data, ...)

Arguments:

    data: the object to be plotted

     ...: Unused

Value:

     A ggplot2 object
于 2012-12-14T19:43:13.043 回答
0

If the argument names need different descriptions, it is acceptable to document the separate methods in separate files. This is not my opinion, it is how they do it in the R source code. And if they do it, it must be right. Look at the documentation pages for the package "stats". Note there are separate files for predict.arima, predict.gls, and so forth.

In the R source, there are several different files for print methods. Observe:

$ find . -name "print*.Rd"
./base/man/print.Rd
./base/man/print.dataframe.Rd
./base/man/print.default.Rd
./stats/man/print.power.htest.Rd
./stats/man/printCoefmat.Rd
./stats/man/print.ts.Rd
./tools/man/print.via.format.Rd`

I do not agree with the previous poster who suggested that you should re-name the arguments if they need different descriptions. That under-cuts the object-oriented idea of polymorphism, which encourages us to not proliferate different names unless necessary.

于 2013-04-22T16:56:08.190 回答