具有构造函数重载的 S4 类在 roxygen2 文档中有重复项

Question

我在 R 包中编写了一个 S4 类。我使用roxygen2 作为文档：

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

后来，我编写了一个重载函数来制作更好的用户界面：

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

我认为我需要记录这两件事，以便无论用户以哪种方式创建 timeframe 对象，智能感知自动完成功能都将起作用。问题是文档加倍了一些事情： 我做错了什么？我该如何解决？

Answer 1

R 文档发生在 per-name，而不是 per-method 或 per-overload 级别。 （有关 Rd 文件的更多信息，请参阅here，这些文件是 Roxygen2 生成的）。这意味着您永远不应该为具有相同名称的对象（无论是函数还是类）添加文档。

想象这两个有不同的内容，然后有人输入help(timeframe)。您希望提供这两个文档中的哪一个？ R 怎么知道区别？

只需定义一次@param 定义（不管是哪个）。自动补全将建议和描述两者的参数。