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

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

Due Diligence:

я нашел упоминание о @slot тег в ранних описаниях roxygen. A 2008 R-forge список рассылки пост кажется укажите, что это мертво, и нет никакой поддержки для @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.

3 294
javascript class-design ios4 slots roxygen2

3 ответа:

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

27

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

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

14