Для документування класів з роксигеном (2), вказівка ​​назви та опису / деталей, схоже, є такими ж, як і для функцій, методів, даних тощо. Однак слоти та успадкування є власним видом тварини. Яка найкраща практика - поточна чи запланована - для документування класів S4 в roxygen2?

Належна старанність:

Я знайшов згадку про @slotтег у ранніх описах роксигену. Повідомлення у списку розсилки R-Forge 2008 року, схоже, вказує на те, що це мертве, і немає підтримки @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), в тому , що немає ніяких @-delimited тегів і слоти можуть йти без документів, без заперечень з боку roxygenize(). Це також нічого не говорить про послідовний спосіб документування успадкування визначеного класу. Я думаю, що залежність, як правило, добре працює (якщо певний слот вимагає не базовий клас з іншого пакету) за допомогою @importтегу.

Отже, підсумовуючи, яка сучасна найкраща практика щодо слотів для Roxygen (2)?

Наразі є три варіанти, які слід розглянути на даний момент:

• A - Деталізований список (як приклад вище).
• Б - @slot... але з додатковими тегами / реалізацією я пропустив. Мені не вдалося змусити @slot працювати з roxygen / roxygen2 у версіях, де він був включений як заміна для деталізованого списку у наведеному вище прикладі. Знову ж, приклад, наведений вище, працює з роксигеном (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

Що стосується бічного сигналу, @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 + та останній документ 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 , щоб робити правильні речі.»