Ответ 1
Официальная поддержка, описанная в документе devtools doc
http://r-pkgs.had.co.nz/man.html#man-classes (прокрутите вниз до подраздела 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 необходим теперь, когда пространство имен требуется для вашего пакета, и вы хотите, чтобы этот метод был доступен для пользователей вашего пакета, а не только другие методы/функции в вашем пакете.
Для документирования методов я обнаружил, что необходимы только две строки, содержащие теги @rdname и @aliases. Оператор @rdname должен точно соответствовать тому, который был указан для общего. Тег @aliases должен придерживаться соглашения об именах, описанного в официальном разделе документации S4 Написание расширений R.
#' @rdname helloworld-methods
#' @aliases helloworld,character,ANY-method
Не должно быть пробелов после запятых в имени @aliases. Я не знаю точных правил, связанных с добавлением ,ANY в конец списка подписи. Кажется, что шаблон состоит в том, что количество элементов во всех списках подписей @aliases должно соответствовать количеству элементов в самом длинном сигнатурном сигнале среди методов. В приведенном ниже примере один из методов определяется с помощью двухэлементной подписи, поэтому R CMD check не удовлетворен документацией, если только ,ANY не был добавлен в тег aliases других методов, даже если их определение подписи только имеет один элемент.
Далее следует полный пример. Я построил это, и он работает без предупреждений на уровне документации от R CMD check testpkg, используя исправленный ошибкой fork очень недавней версии версии 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 над общим определением. Это имеет некоторый базис в коде, поскольку общий должен включать все конкретные аргументы, которые появляются в любом из впоследствии определенных методов. Обратите внимание, что аргументы, которые обрабатываются как часть ... в списке аргументов, не включаются и не должны быть документально оформлены, но сам ... должен быть задокументирован выше общего (см. Полный пример ниже).
Для получения дополнительной информации об основах документирования функций существует wiki, старая рогенговая виньетка, а также сайт разработки roxygen2 на github. Существует также SO вопрос о документации R с Roxygen в целом.