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

Question

Я видел некоторые дискуссии в SO и в других местах, касающихся того, как это должно быть или будет проводиться в будущих версиях Roxygen2. Однако я застрял. Как я должен документировать общий S4, а также его методы, используя Roxygen2? Рабочий пример для совершенно новых общих/методов, а также пример для расширения базового S4 Generic был бы невероятно полезен. Я не хочу делать отдельную (в основном) избыточную документацию для каждого метода S4 одного и того же общего.

Due Dilligence: я отслеживал полезный пример для метода «экстракта». Тем не менее, это кажется устаревшим и неполным для моего вопроса. Он использует тег @Slot в документации в классе, который не поддерживается (больше не?). Он показывает только расширение основного метода S4 «[», а не полный пример Roxygen, включая документацию S4 Generic.

Как правильно документировать S4 [" и [<-" Методы с использованием roxygen?

Если я полностью документирует новый S4 Generic с заголовком, описание @param @return @name @aliases @docType @rdname, а затем документируйте метод S4 только с соответствующим @name @aliases @docType @rdname, Я получаю следующее R CMD check предупреждение:

* checking for missing documentation entries ... WARNING
Undocumented S4 methods:
<< long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' >>
All user-level objects in a package (including S4 classes and methods)
should have documentation entries.

Сначала он смотрел так, как будто ни один из моих методов S4 не задокументирован таким образом с Roxygen2, фактически не работал. Однако до сих пор я заметил, что мои расширения основного метода «показывать» не имеют связанной с этим ошибки, хотя они были задокументированы точно так же, как и все остальные. Вот пример полной документации Roxygen, которую я включил выше одного из методов шоу, который не генерировал ошибку отсутствующего документации:

#' @name show
#' @aliases show,myClass2-method
#' @docType methods
#' @rdname show-methods

Таким образом, я в растерянности. Как видите, я включил соглашение о псевдонимах для методов S4, описанных в Раздел документации S4 Руководства по пакетированию R, а именно, что методы должны иметь псевдоним со следующим именем (без пространства):

generic,signature_list-method.

Каким -то образом, это не совсем понятно R CMD check.

Наконец, после создания документации с использованием:

library("devtools")
library("roxygen2")
document("mypkgname")
check_doc("mypkgname")

И создавая пакет, я получаю функционирующую документацию. Любые названия из документации конкретного метода входят в поле «Описание», довольно неловко. Таким образом, Roxygen2, очевидно, сделал что -то с документацией каждого метода и находится на правильном пути. Однако этого недостаточно, чтобы избежать большого и тревожного предупреждения от

> R CMD check mypkgname

Я посмотрел на RD -файлы, но я еще меньше знаю о них, чтобы быстро увидеть, в чем проблема, и я все равно хочу знать решение Roxygen2, чтобы мне не пришлось манипулировать файлами RD сразу после каждой пересмотра документации.

Так что это многочисленный вопрос:

1. Каков текущий рекомендуемый подход как для документации S4 Generic, так и для метода S4 с Roxygen2?

2. Есть ли где -то хороший пример, который показывает полную информацию?

3. Что может быть причиной и решением, чтобы предупреждение о том, что документация для большинства методов S4 отсутствует (даже несмотря на то, что методы с «отсутствующей» документацией фактически проанализировали свои документы Roxygen2, и полученные файлы RD хотя бы достаточно хороши, чтобы работать. в пакете после R CMD build mypkgname) ?

Answer 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 Generics я нахожу следующие три строки, необходимые в большинстве моих общих заголовков:

#' @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 был добавлен в тег псевдонимов других методов, даже если их определение подписи имеет только один элемент.

Полный пример следует. Я построил это, и он работает без предупреждений на уровне документации R CMD check testpkg, используя ФИКСИНА ФИКСА ОБЕСПЕЧЕНИЯ Недавней версии DEVEL ROXYGEN2 (которую я сделал доступным). Анкет Для быстрой установки этой вилки в вашу систему используйте library("devtools"); install_github("roxygen", "joey711"). Анкет Самая последняя версия Roxygen2 не будет работать в этот момент из -за ошибки цитаты (описанной в отдельном ответе), но я ожидаю, что это будет включено очень скоро, и моя вилка не понадобится. Для просмотра этого примера в контексте остальной части пакета и просмотра полученных файлов документации (RD), я сделал его доступным в виде тривиального тестового пакета на GitHub Call 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 тег, но детали будут лучше обработаны отдельным, поэтому вопрос.

Таким образом, большая часть вашей документации входит в заголовок Roxygen над общим определением. Это имеет некоторую основу в коде, поскольку Generic должен включать все конкретные аргументы, которые появляются в любом из впоследствии определенных методов. Обратите внимание, что аргументы, которые рассматриваются как часть ... в список аргументов не включены и не должны быть задокументированы конкретно, но ... Сама должна быть задокументирована над общим (см. Полный пример ниже).

Для получения более подробной информации о основах функций документирования, есть Вики в процессе, Старая виньетка Roxygen, так же хорошо как сайт разработки Roxygen2 на GitHub. Анкет Есть также Так что вопрос о документации R с Roxygen в целом.

Answer 2

Я отслеживал, что ответ на часть (3)-не очень пропущенная документация методов S4-из-за того, что цитаты добавляются ошибочно вокруг тегов псевдонима, когда используется соглашение о именовании S4; Скорее всего, ошибка, возникающая в результате текстового обращения с псевдонимом, который содержит запятую как часть его названия. Это все еще верно для последней версии Roxygen2 во время этой публикации. Я только что опубликовал более тщательное описание ошибки с воспроизводимым примером на странице RoxyGen2 GitHub:

https://github.com/klutometis/roxygen/issues/40

Вкратце,

#' @aliases show,helloworld-method

становится

\alias{"show,helloworld-method"}

в полученном файле RD. Удаление цитат удаляет R CMD check Предупреждение и документация создает и функциональна в обоих случаях.

Я думаю, что части (1) и (2) этого вопроса (лучшие практики; хорошие примеры) все еще остаются открытыми.