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

Question

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

Due Diligence:

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

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

На данный момент есть три варианта для рассмотрения:

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

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

Answer 1

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

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

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

Answer 2

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

Answer 3

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