Как правильно документировать методы S4 с помощью roxygen2 - программирование
Подтвердить что ты не робот

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

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

Due dilligence: Я нашел полезный пример для метода "extract". Однако, по моему мнению, он является устаревшим и неполным. Он использует тег @slot в документации по классу, который не поддерживается (больше не поддерживается). Он показывает только расширение основного S4-метода "[", а не полный пример Roxygen, включая документацию по S4 generic.

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

Если я полностью документирую новый родовой файл S4 с заголовком, описанием @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, фактически не работал. Однако до сих пор я заметил, что мои расширения основного метода "show" не имеют связанной ошибки, хотя они были задокументированы точно так же, как и остальные. Ниже приведен пример полной документации по roxygen, включенной выше одного из методов show, который НЕ генерировал ошибку с отсутствующей документацией:

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

Итак, это вопрос с несколькими вопросами:

  • Каков нынешний рекомендуемый подход как для документации по S4, так и для S4 с помощью roxygen2?

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

  • Какова может быть причина и решение для предупреждения о том, что документация для большинства методов S4 отсутствует (даже если методы с "отсутствующей" документацией фактически имели свой документ, обработанный roxygen2, и полученные Rd файлы по крайней мере, достаточно, чтобы работать в пакете после R CMD build mypkgname)?

4b9b3361

ОТВЕТЫ

Ответ 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 в целом.

Ответ 2

Я выяснил, что ответ на часть (3) - документация о методах S4, которая не является отсутствующей, связана с тем, что кавычки добавляются ошибочно вокруг тегов \alias, когда используется соглашение об именах 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) этого вопроса (лучшие практики, хорошие примеры) все еще остаются открытыми.