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

Для документирования классов с помощью roxygen (2) указание заголовка и описания / деталей похоже на то же самое, что и для функций, методов, данных и т. Д. Однако слоты и наследование - это своего рода животные. Какая лучшая практика - текущая или планируемая - для документирования классов S4 в roxygen2?

Юридическая экспертиза:

Я нашел упоминание о теге @slot в ранних описаниях roxygen. Сообщение из списка рассылки R-forge 2008 года, похоже, указывает на то, что он мертв, и в roxygen нет поддержки @slot:

Это верно для 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), поскольку отсутствуют теги с разделителями @, и слоты могут остаться недокументированными без возражений со стороны roxygenize(). В нем также ничего не говорится о последовательном способе документирования наследования определяемого класса. Я полагаю, что зависимость по-прежнему работает нормально (если конкретный слот требует небазового класса из другого пакета) с использованием тега @import.

Итак, чтобы подвести итог, какова в настоящее время лучшая практика для слотов roxygen (2)?

На данный момент, похоже, есть три варианта, которые следует рассмотреть:

  • A - Детализированный список (как в примере выше).
  • B - @slot ... но с лишними тегами / реализацией я пропустил. Мне не удалось заставить @slot работать с roxygen / roxygen2 в версиях, где он был включен в качестве замены детализированного списка в приведенном выше примере. Опять же, приведенный выше пример действительно работает с roxygen (2).
  • C - Альтернативный тег для указания слотов, например @param, который выполняет то же самое.

Я заимствую / расширяю этот вопрос из сообщения, которое я опубликовал на roxygen2 странице разработки на github.


r class roxygen2 slot s4
person Paul McMurdie    schedule 09.09.2011    source источник
comment
@slot - это, вероятно, то, что вы хотите в долгосрочной перспективе, но сначала это должно быть реализовано ...   -  person hadley    schedule 14.09.2011
comment
Спасибо! Это хорошо знать. Я рад, что в моем коде гораздо меньше setClass операторов, чем setMethod. Внесение изменений после того, как @slot будет реализовано, не будет слишком болезненным.   -  person Paul McMurdie    schedule 15.09.2011
comment
Обсуждение @slot: github.com/klutometis/roxygen/pull/85   -  person Brian Diggs    schedule 21.03.2012
comment
Связанный вопрос: stackoverflow.com/questions/13642092/   -  person Joris Meys    schedule 30.11.2012
comment
Классы S4 теперь полностью поддерживаются в Roxygen2 версии 3 (доступно на github ).   -  person Gregor Thomas    schedule 09.12.2013

Ответы (3)


arrow_upward
30
arrow_downward

Обновленный ответ для Roxygen2 5.0.1, текущая версия 6.0.1

Для S4 лучшая практика сейчас - это документирование с использованием тега @slot:

#' The title for my S4 class that extends \code{"character"} class.
#'
#' Some details about this class and my plans for it in the body.
#'
#' @slot myslot1 A logical keeping track of something.
#' @slot myslot2 An integer specifying something else.
#' @slot myslot3 A data.frame holding some data.
#'
#' @name mynewclass-class
#' @rdname mynewclass-class
#' @export

Кстати, @exportClass требуется только в некоторых случаях, сейчас общий способ экспорта функции - использовать @export. Вам также не нужно экспортировать класс, если вы не хотите, чтобы другие пакеты могли расширять класс.

См. Также http://r-pkgs.had.co.nz/namespace.html#exports

Обновленный ответ для Roygen2 3.0.0, актуальный по состоянию на 5.0.1.

Для S4 лучшая практика - это документация в форме:

#'  \section{Slots}{
#'    \describe{
#'      \item{\code{a}:}{Object of class \code{"numeric"}.}
#'      \item{\code{b}:}{Object of class \code{"character"}.}
#'    }
#'  }

Это согласуется с внутренним представлением слотов в виде списка внутри объекта. Как вы указываете, этот синтаксис отличается от других строк, и мы можем надеяться на более надежное решение в будущем, включающее знания о наследовании, но сегодня этого не существует.

Как указал @Brian Diggs, эта функция была перенесена в 3.0.0, дальнейшее обсуждение на https://github.com/klutometis/roxygen/pull/85

person William Entriken    schedule 08.06.2012
comment
Вы использовали реализацию @Brian Diggs? Это работает? Как вы думаете, можете ли вы предоставить некоторые подробности об этом подходе (и, следовательно, о чем-то похожем на решение @slot). Я не дошел до того, чтобы попробовать это, ожидая (возможно, лениво) этого ожидающего решения @slot. Я знаю, что вопрос задается не так, но, судя по комментариям (включая @ hadley), кажется, что @slot - настоящий ответ. Я согласен с вашей оценкой, что подробный список (как в моем вопросе) является текущей лучшей практикой, хотя, надеюсь, скоро будет заменен. - person Paul McMurdie; 09.06.2012

arrow_upward
19
arrow_downward

Решение, предоставляемое Full Decent, подходит, если вы собираетесь документировать слоты в самих файлах Rd. При использовании roxygen2 вы можете использовать тег @section, чтобы сделать то же самое с \describe. Пример:

#' The EXAMPLE class
#'
#' This class contains an example. This line goes into the description
#'
#' This line and the next ones go into the details.
#' This line thus appears in the details as well.
#'
#'@section Slots: 
#'  \describe{
#'    \item{\code{slot1}:}{Matrix of class \code{"numeric"}, containing data from slot1}
#'    \item{\code{slot2}:}{Object of class \code{"character"}, containing data that needs to go in slot2.}
#'  }
#'
#' @note You can still add notes
#' @name EXAMPLE 
#' @rdname EXAMPLE
#' @aliases EXAMPLE-class
#' @exportClass EXAMPLE
#' @author Joris Meys
person Joris Meys    schedule 09.01.2013

arrow_upward
15
arrow_downward

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, чтобы поступить правильно».

person Paul McMurdie    schedule 10.12.2013
comment
@slot работает отлично, вы также можете использовать его (или @field) для подделки документа класса S3. - person Brandon Bertelsen; 21.06.2015