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

Question

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

Комплексная проверка:

Я обнаружил упоминание тега @slot в ранних описаниях roxygen. Сообщение из списка рассылки R-forge 2008 года кажется, указывает на то, что это мертво, и в roxygen нет поддержки для генерирования кода кода:

Верно ли это в отношении roxygen2? Ранее упомянутый пост предлагает пользователю вместо этого создать свой собственный список с разметкой LaTeX. Например. новый класс S4, расширяющий класс @slot, будет закодирован и задокументирован следующим образом:

родовое слово

Тем не менее, хотя это работает, этот подход для документирования слотов кажется несовместимым с остальной частью roxygen (2), поскольку отсутствуют теги, разделенные сгенерированными кодовыми кодами, и слоты могут остаться недокументированными без возражений со стороны "character". В нем также ничего не говорится о последовательном способе документирования наследования определяемого класса. Я полагаю, что зависимость по-прежнему работает нормально (если конкретный слот требует небазового класса из другого пакета) с использованием тега \describe.

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

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

<цитата>

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

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

Answer 1

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

Answer 2

Обновленный ответ для Roxygen2 5.0.1, текущая версия 6.0.1

Для S4 наилучшей практикой является документирование с использованием тега @slot:

родовое слово

Отметим, что @exportClass необходим только в некоторых случаях, сейчас основной способ экспорта функции - это использовать @export. Вам также не нужно экспортировать класс, если вы не хотите, чтобы другие пакеты могли расширять класс.

См. также http://r-pkgs.had.co.nz/ namespace.html # exports

Обновленный ответ для Roygen2 3.0.0, актуальный по состоянию на 5.0.1.

Для S4 рекомендуется документация в форме:

родовое слово

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

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

Answer 3

Решение, предоставляемое Full Decent, подходит, если вы собираетесь документировать слоты в самих файлах Rd.При использовании roxygen2 вы можете использовать тег @section, чтобы сделать то же самое с \describe.Пример:

родовое слово