Документирование двух методов S3 в одном файле с Roxygen

У меня есть два метода для общего 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 для создания юридического (не дублирующего аргумента) из нескольких методов? Если нет, то каков наилучший способ справиться с этим сценарием?

Ответы

Ответ 1

Я думаю, что идея общих методов S3 заключается в том, что не обязательно иметь разные описания для одного и того же аргумента.

Из раздела использования видно, какие классы приняты (для аргумента, на котором происходит отправка), если вы создаете документацию по S3 с ##' @method и ##' @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

Ответ 2

Если именам аргументов нужны разные описания, допустимо документировать отдельные методы в отдельных файлах. Это не мое мнение, так они делают это в исходном коде R. И если они это сделают, это должно быть правильно. Посмотрите на страницы документации для пакета "stats". Обратите внимание, что существуют отдельные файлы для прогноза .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`

Я не согласен с предыдущим плакатом, который предложил вам переименовать аргументы, если им нужны разные описания. Это подрывает объектно-ориентированную идею полиморфизма, что побуждает нас не размножать разные имена, если это необходимо.