使用Roxygen在同一文件中记录两个S3方法

时间:2012-04-10 19:55:37

标签: r documentation roxygen2

我有两种方法用于密切相关的S3泛型(在另一个包中定义),因此我想在同一Rd文件中记录它们。但是,当我单独记录他们的参数时,我收到R CMD check关于“文档对象中的重复\参数条目”的警告

##' 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以创建合法(不重复参数)?如果没有,处理这种情况的最佳方法是什么?

2 个答案:

答案 0 :(得分:2)

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

如果使用##' @method##' @S3method生成S3方法文档,则从使用部分可以清楚地了解哪些类(对于发生调度的参数)。对于其他参数,我会说需要不同的描述可能表明应该使用不同的参数名称。

所以来自:

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

答案 1 :(得分:0)

如果参数名称需要不同的描述,则可以在单独的文件中记录单独的方法。这不是我的意见,它是他们在R源代码中的做法。如果他们这样做,那一定是对的。查看包“stats”的文档页面。请注意,predict.arima,predict.gls等有单独的文件。

在R源代码中,有几种不同的打印方法文件。观察:

$ 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`

我不同意之前的海报,他建议如果需要不同的描述,你应该重新命名参数。这削弱了面向对象的多态性思想,这种思想鼓励我们除非必要,否则不要扩散不同的名称。