Для документирования классов с помощью 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 .

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

На sidenote, @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.

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

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