Для документирования классов с помощью roxygen (2) указание заголовка и описания / подробностей выглядит так же, как для функций, методов, данных и т. Д. Однако слоты и наследование являются своего рода животными. Какова лучшая практика - текущая или планируемая - для документирования классов S4 в roxygen2?
Юридическая экспертиза:
Я нашел упоминание о @slot
метке в ранних описаниях кислорода.
Сообщение в списке рассылки R-forge 2008,
похоже, указывает на то, что оно мертво, и @slot
в roxygen нет поддержки :
Это правда о roxygen2? Ранее упоминавшаяся публикация предполагает, что пользователь должен вместо этого создать свой собственный список с разметкой LaTeX. Например, новый класс S4, который расширяет "character"
класс, будет закодирован и задокументирован так:
#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' \describe{
#' \item{myslot1}{A logical keeping track of something.}
#'
#' \item{myslot2}{An integer specifying something else.}
#'
#' \item{myslot3}{A data.frame holding some data.}
#' }
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @exportClass mynewclass
setClass("mynewclass",
representation(myslot1="logical",
myslot2="integer",
myslot3="data.frame"),
contains = "character"
)
Однако, несмотря на это работает, это \describe
, \item
подход для документирования слотов кажется несовместимым с остальной частью roxygen (2), в том , что нет никаких @
-delimited тегов и слоты могут идти без документов, без возражений со стороны roxygenize()
. В нем также ничего не говорится о последовательном способе документирования наследования определяемого класса. Я предполагаю, что зависимость все еще обычно работает нормально (если конкретный слот требует не базовый класс из другого пакета), используя @import
тег.
Итак, подведем итог: какова текущая наилучшая практика для слотов roxygen (2)?
Кажется, на данный момент есть три варианта для рассмотрения:
- A - Детализированный список (как пример выше).
- B -
@slot
... но с дополнительными тегами / реализацией я пропустил. Мне не удалось заставить @slot работать с roxygen / roxygen2 в версиях, где он был включен в качестве замены для подробного списка в приведенном выше примере. Опять же, приведенный выше пример работает с roxygen (2).- C - некоторый альтернативный тег для указания слотов, например
@param
, который может выполнить то же самое.
Я заимствую / расширяю этот вопрос из поста, который я сделал, на roxygen2
странице разработки на github .
@slot
это, вероятно, то, что вы хотите в долгосрочной перспективе, но это должно быть реализовано в первую очередь ...setClass
операторов, чемsetMethod
. Внесение изменений после внесения изменений@slot
не будет слишком болезненным.Ответы:
Обновленный ответ для Roxygen2 5.0.1, актуальный на 6.0.1
Для S4 лучшая практика сейчас - документирование с использованием
@slot
тега:На sidenote,
@exportClass
это необходимо только в некоторых случаях, общий способ экспорта функции используется@export
сейчас. Вам также не нужно экспортировать класс, если вы не хотите, чтобы другие пакеты могли расширять класс.Смотрите также http://r-pkgs.had.co.nz/namespace.html#exports
Обновленный ответ для Roygen2 3.0.0, актуальный на 5.0.1.
Для S4 лучшая практика - это документация в форме:
Это согласуется с внутренним представлением слотов в виде списка внутри объекта. Как вы указали, этот синтаксис отличается от других строк, и мы можем надеяться на более надежное решение в будущем, которое будет включать в себя знания о наследовании - но сегодня этого не существует.
Как отметил @Brian Diggs, эта функция была перенесена в 3.0.0, дальнейшее обсуждение на https://github.com/klutometis/roxygen/pull/85.
источник
@slot
решение). Я не удосужился попробовать это, ожидая (возможно, лениво) этого ожидающего@slot
решения. Я знаю, что это не то, как ставится вопрос, но, основываясь на комментариях (включая @ hadley's), кажется,@slot
что это «реальный» ответ. Я согласен с вашей оценкой того, что подробный список (как и в моем вопросе) является текущей наилучшей практикой, хотя, надеюсь, вскоре будет заменен.Решение, предоставленное Full Decent, подходит для документирования слотов в файлах Rd. При использовании
roxygen2
вы можете использовать тег,@section
чтобы сделать то же самое с\describe
. Пример:источник
roxygen2 v4.1 + и последний документ Хэдли для этого:
http://r-pkgs.had.co.nz/man.html#man-classes
Я еще не пробовал это для RC, но у меня это работает для S4 сейчас.
предварительно
Похоже, что слоты класса S4 полностью поддерживаются в Roxygen2 версии 3.0+:
http://blog.rstudio.org/2013/12/09/roxygen2-3-0-0/
«Документируйте свои классы S4, методы S4 и классы RC с помощью roxygen2 - вы можете безопасно удалить обходные пути, которые использовали
@alias
и@usage
, и просто полагаться на roxygen2, чтобы поступать правильно».источник