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

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

Due Diligence:

Я нашел упоминание тега @slot в ранних описаниях roxygen. Сообщение о рассылке 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.

Ответы

Ответ 1

roxygen2 v4.1 + и последний документ Hadley для этого:

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 для правильной работы."

Ответ 2

Обновленный ответ для 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

Ответ 3

Решение, предоставляемое 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