Официальная поддержка, объяснено в документации devtools
http://r -pkgs.had.co.nz / man.html # человеко-классы
(прокрутите вниз до подраздела S4 ).
Текущий короткий пример с этой страницы воспроизводится в следующем (для удобства):
#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
slots = list(balance = "numeric")
)
Приведенная выше ссылка очень четко объясняет поддержку S3, S4 и RC через roxygen / devtools. Приведенное здесь объяснение должно заменить замену старого ответа ниже, который пока работает, но менее ясен и более сложен.
Старый ответ
Вот пример, который должен работать для большинства методов S4.
Для документирования универсальных S4 я нахожу следующие три строки, необходимые в большинстве моих универсальных заголовков:
#' @export
#' @docType methods
#' @rdname helloworld-methods
Где helloworld-methods заменено на the_name_of_your_generic-methods. Это будет имя Rd-файла, который содержит документацию для универсального и всех его методов. Это соглашение об именах не является обязательным, но распространенным и полезным. Тег @export необходим теперь, когда для вашего пакета требуется пространство имен, и вы хотите, чтобы этот метод был доступен пользователям вашего пакета, а не только другим методам / функциям в вашем пакете.
Я считаю, что для документирования методов необходимы только 2 строки с тегами @rdname и @aliases. Оператор @rdname должен точно совпадать с оператором для универсального выражения. Тег @aliases должен соответствовать соглашению об именах, описанному в официальном разделе документации S4 Запись расширений R .
#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
После запятых в имени @aliases не должно быть пробелов. Я не знаю точных правил, касающихся добавления ,ANY в конец списка подписей. Кажется, что шаблон состоит в том, что количество элементов во всех @aliases списках сигнатур должно соответствовать количеству элементов в самом длинном векторе сигнатуры среди методов. В приведенном ниже примере один из методов определен с 2-элементной сигнатурой, и поэтому R CMD check не был удовлетворен документацией, если ,ANY не был добавлен к тегу aliases других методов, даже если только их определение сигнатуры имеет один элемент.
Полный пример приведен ниже. Я построил это, и оно работает без предупреждений на уровне документации от R CMD check testpkg, используя исправленную ошибку вилку очень недавней версии devel roxygen2 (которую я сделал доступной) . Для быстрой установки этой вилки в вашей системе используйте library("devtools"); install_github("roxygen", "joey711"). Самая последняя версия roxygen2 не будет работать в этот момент из-за ошибки цитаты (описанной в отдельном ответе), но я ожидаю, что она будет включена очень скоро, и мой форк не понадобится. Для просмотра этого примера в контексте остальной части пакета и просмотра итоговых файлов документации (Rd) я сделал его доступным как тривиальный тестовый пакет на github под названием testpkg .
##############################################################
#' The title, in this case: Helloworld-ify the argument.
#'
#' Some additional details about this S4 generic and its methods.
#' The extra blank line between this section and the title is
#' critical for roxygen2 to differentiate the title from the
#' description section.
#'
#' @param x Description of \code{x}. The main argument in this
#' example. Most often has such and such properties.
#'
#' @param y Description of \code{y}. An argument that is rarely
#' used by \code{"helloworld"} methods.
#'
#' @param ... Additional argument list that might not ever
#' be used.
#'
#' @return A helloworld-ified argument. Oh, you'll see.
#'
#' @seealso \code{\link{print}} and \code{\link{cat}}
#'
#' @export
#' @docType methods
#' @rdname helloworld-methods
#'
#' @examples
#' helloworld("thisismystring")
#' helloworld(char2helloworld("thisismystring"))
#' helloworld(matrix(0,3,3))
#' helloworld(list(0,0,0))
#' helloworld(integer(0))
setGeneric("helloworld", function(x, y, ...){
cat("Hello World!")
cat("\n")
standardGeneric("helloworld")
})
#' @rdname helloworld-methods
#' @aliases helloworld,ANY,ANY-method
setMethod("helloworld", "ANY", function(x, y, ...){
cat(class(x))
})
#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
setMethod("helloworld", "character", function(x){
show(x)
})
#' @rdname helloworld-methods
#' @aliases helloworld,character,character-method
setMethod("helloworld", c("character", "character"), function(x, y){
show(x)
})
В этом примере предполагается, что вам не нужна отдельная документация по конкретному методу, потому что ваши методы не сильно отклоняются от поведения, которое можно ожидать на основе универсального документа. В roxygen2 есть средства для обработки этого альтернативного случая с использованием тега @usage, но детали лучше обработать отдельным вопросом SO.
Таким образом, большая часть ваших усилий по документированию идет в заголовке roxygen над общим определением. Это имеет некоторую основу в коде, так как универсальный должен включать все конкретные аргументы, которые появляются в любом из впоследствии определенных методов. Обратите внимание, что аргументы, которые обрабатываются как часть ... в списке аргументов, не включены и не должны специально документироваться, но сам ... должен быть задокументирован также и над родовым (см. Полный пример ниже).
Для получения более подробной информации об основах документирования функций, существует вики , старая виньетка roxygen , а также сайт разработки roxygen2 на github . Существует также SO вопрос по документации R с Roxygen в целом.