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

Я написал класс 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. Проблема в том, что документация дублирует некоторые вещи: введите здесь описание изображения Что я делаю не так? Как это исправить?


person lebelinoz    schedule 04.05.2017    source источник


Ответы (1)


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

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

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

person David Robinson    schedule 04.05.2017
comment
Я заменил @slot строк на @param строк, а комментарии над перегруженной функцией теперь представляют собой однострочные #' @export. Кажется, это работает. Спасибо. - person lebelinoz; 04.05.2017