Search code examples
rdevtoolsr-s4roxygen2

S4 class with constructor overload has duplicates in roxygen2 documentation

I have written an S4 class in an R package. I use roxygen2 for the documentation:

#' A timeframe class represents a start date, end date and frequency
#'
#' @slot start_date First date in the timespan
#' @slot end_date Last date in the timespan
#' @slot frequency 'D', 'W' or 'M' for daily, weekly or monthly
#' @export
#' @exportClass timeframe
timeframe <- setClass( "timeframe", slots = c(start_date = "Date", end_date = "Date", frequency = "character"),
    prototype = list(
        start_date = lubridate::as_date(lubridate::today() - 367),
        end_date = lubridate::as_date(lubridate::today() - 1),
        frequency = "D"
    ),
    validity = function(object) {
        # ...some validation stuff...
    }
)

Later, I write an overload function to make for a nicer user interface:

#' @param start_date First date in the timespan
#' @param end_date Last date in the timespan
#' @param frequency 'D', 'W' or 'M' for daily, weekly or monthly
#' @export
timeframe <- function(start_date, end_date, frequency = "D") {
    # ...some validation steps, such as setting default dates if they're missing...
    return_object = new("timeframe", start_date = start_date, end_date = end_date, frequency = frequency)
    return(return_object)
}

I think I need to document both things so the intellisense autocompletion will work regardless of which way a user creates a timeframe object. The problem is that the documentation doubles up some things: enter image description here What am I doing wrong? How do I fix it?

Solution

  • R documentation happens on a per-name, not a per-method or per-overload level. (See here for more on Rd files, which are what Roxygen2 generates). This means you should never double up on documentation for objects (whether functions or classes) with the same name.

    Imagine the two had different content, then someone typed help(timeframe). Which of the two documentations would you expect to come up? How would R know the difference?

    Just define the @param definitions once (doesn't matter which). The autocompletion will suggest and describe parameters for either.