Класс S4 с перегрузкой конструктора имеет дубликаты в документации roxygen2

Question

Я написал класс S4 в пакете R. я использую 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)
}

Я думаю, что мне нужно документировать обе вещи, чтобы автозаполнение intellisense работало независимо от того, каким образом пользователь создает timeframe объект. Проблема в том, что документация удваивает некоторые вещи: Что я делаю неправильно? Как мне это исправить?

Answer 1

Документация R происходит для каждого имени, а не для метода или уровня перегрузки. (Подробнее о файлах R d, которые генерирует Roxygen2, смотрите здесь). Это означает, что вы никогда не должны дублировать документацию для объектов (будь то функции или классы) с одинаковыми именами.

Представьте, что у обоих было разное содержание, потом кто-то напечатал help(timeframe), Какую из двух документов вы ожидаете увидеть? Как R узнает разницу?

Просто определите @param определения один раз (не важно, какие). Автозаполнение предложит и опишет параметры для любого из них.