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

Question

我的S3泛型函数有两个方法（来自另一个包），它们非常相关，因此我想将它们记录在同一个Rd文件中。但是，当我单独记录它们的参数时，R CMD check会发出警告，指出“Duplicated \argument entries in documentation object”。

##' 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从多个方法中创建合法的（不重复参数）？如果不行，如何处理这种情况？

- Brian Diggs

---

不需要复制和粘贴相同的文本，您需要提供英语文本以供翻译。 - Brandon Bertelsen

@BrandonBertelsen 但是这样两个文本都必须描述两种情况，这会破坏文档的分隔。 - Brian Diggs

@BrianDiggs 你有没有找到一个好的方法来做这件事？ - Dason

如果这些都在同一个Rd文件中，那么难道不应该只有一个@param覆盖两种方法吗？如果你手写Rd文件，你会写\item{data}{an object of class \code{"survfit"} or \code{"survfit.fortify} as returned by \code{\link{survfit}} or \code{\link{fortify.survfit}}。重复记录这个参数没有意义，而且Rd解析器也不允许这样做。我会在第一个S3方法的文档块中只写一个@param data blah blah（如上所述）并将其留在那里。 - Gavin Simpson

我看不出有什么方法可以避免这种情况，考虑到roxygen2的一般工作方式和Rd文件的要求。 - Gavin Simpson

Answer 1

我认为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

- cbeleites unhappy with SX

Answer 2

如果参数名称需要不同的描述，可以将单独的方法文档记录在单独的文件中。这不是我的意见，而是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`

我不同意之前的发帖者建议，即如果需要不同的描述，则应重新命名参数。这会削弱面向对象的多态思想，该思想鼓励我们在不必要的情况下不要大量使用不同的名称。

- pauljohn32