Documenting two S3 methods in the same file with Roxygen

Question

I have two methods for an S3 generic (defined in another package) that are closely related and so I wanted to document them in the same Rd file. However, when I document their arguments separately, I get a warning from R CMD check about "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
}

The first argument must be data because that is what the generic defines. However, the documentation for it is different for the different methods, if only because it must be of a different class. I could have two separate documentation files for this, but they are closely coupled so I would like to keep them together. I could list all possible classes of data in the first invocation and not have anything in the subsequent ones, but that means I'm documenting the second function with the first rather than keeping it all together as is the point of Roxygen.

Is it possible to get roxygen to create a legal (not duplicating the argument) from multiple methods? If not, what is the best way to handle this scenario?

Answer 1

I think the idea behind S3 generic methods is that it should not be necessary to have different descriptions for the same argument.

It is clear from the usage section which classes are accepted (for the argument on which the dispatch takes place), if you produce S3 method documentation with ##' @method and ##' @S3method. For the other arguments, I'd say that needing different descriptions is probably an indicator that different argument names should be used.

So from:

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

I get with 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