Презентация к 8 уроку курса разработка пакетов на языке R

1. Документирование функций
вашего пакета
Разработка документации с помощью roxygen2
Алексей Селезнёв

2. Мой telegram канал

3. Какие компонентыпакета отвечают за документацию
• Над функциями и другими объектами, которые вам надо задокументировать вы
прописываете специальные roxygen комментарии
• После генерации все файлы документации хранятся в каталоге man/.

4. Рабочий процесс
1. Добавляете roxygen2 комментарии над объектами, к которым хотите сгенерировать
документацию (Ctrl+Shift+Alt+R когда курсор находится внутри кода функции или кода
генерирующего объект)
2. Запускаете devtools::document() (Ctrl/Cmd + Shift + D), чтобы преобразовать комментарии
roxygen2 в .Rd файлы.
3. Запускаете предварительный просмотрт сгенерированной документации с помощью
?function_name.
4. Исправляете ошибки, повторяете процесс до тех пор, пока не получите нужный
результат.

5. Структура roxygen комментариев
• Комментарии roxygen2 начинаются с #’
• Все комментарии roxygen2, предшествующие функции называются блоком
• Блоки разбиваются на теги , которые выглядят как @tagName tagValue
• По умолчанию каждый блок генерирует один топик документации , т.е. один .Rd файл в
man/ каталоге.

6. Особенности разметки
• Используйте апострофы для выделения блока текста как кода: #' I like `thisfunction()`,
because it's great.
• Для добавление ссылки на документацию к другой функции вашего или стороннего пакета
используйте квадратные скобки:
#' It's obvious that `thisfunction()` is better than [otherpkg::otherfunction()]
#' or even our own [olderfunction()].
• Ссылайтесь на виньетки с помощью кода: vignette("rd-formatting", package = "roxygen2")
• Маркированные списки прописываются так же, как и в обычном markdown:
#' Best features of `thisfunction()`:
#' * Smells nice
#' * Has good vibes

7. Разделыдокументации
• Заголовок (@title) – Обычно задаётся позиционно в первой строке roxygen комментария
• Описание (@description) – Более подробное описание, что делает ваша функция, можно
задать позиционно, второй строкой roxygen комментария
• Детали (@details) – Тут описывают важные детали использования вашей функций, можно
задать позиционно третей строкой комментария
• Аргументы функции (@param) – Описание каждого аргумента функции
• Возвращаемое значение (@return) – Какой объект возвращает ваша функция
• Примеры (@examples) – Примеры использования вашей функции

8. Title, description и details
• Первые 3 тега roxygen можно использовать позиционно, без указания их названий:
• Title – заголовок должен быть написан в регистре заголовков, не заканчиваться точкой и после него
должна идти пустая строка.
• Description – более подробное описание того, что делает функция, как правило занимает один абзац.
Если ваше описание требует более чем один абзац вам придётся явно использовать тег @description.
• Details – описание деталей работы вашей функции, в осном этот блок не используется в
документации. Хорошей практикой является создание пользовательских разделов подробностей с
помощью тега @section.

9. Аргументы
• Для документирования аргументов функции используйте тег @param
• Если использование нескольких аргументов тесно связано между собой можете
объединить их через запятую, без указания пробела: #' @param x,y A pair of character
vectors.
• Тег @inheritParams позволяет наследовать описание аргументов из других функций вашего
или даже стороннего пакета. При этом будут унаследованы только те аргументы, которые
присутвуют в новой функции, и которые в ней отдельно не были задокументированы.

10. Возвращаемое значение
• За возвращаемое значение отвечает тег @returns
• Для возвращаемого значения вам необходимо описать класс, тип и размер возвращаемого
функцией значения.

11. Примеры
• Примеры описываются с использованием тега @examples
• Все прописанные примеры должны выполняться без ошибок, поскольку они регулярно
проверяются:
• В интерактивном режиме с помощью команды example()
• Во время работы R CMD check на вашем компьютере
• Во время проверки R CMD check на CRAN.
• Когда генерируется веб-сайт вашего пакета с помощью pkgdown
• При использовании нестабильных ресурсов в ваших примерах, например веб-сайтах
используйте тег @examplesIf, который позволяет пропускать такие примеры, так же можно
завернуть ваши примеры в dontrun{}, для избегания запуска примеров, которые заведомо
заканчиваются ошибками.

12. Повторное использование документации
• При необходимости объединить документацию нескольких функций в один файл
документации используйте тег @rdname, и передайте в него название функции, в которой
подробно описана документация всех функций.
• Теги отвечающие за наследование частей документации:
• @inherit source_function - унаследует все поддерживаемые компоненты от source_function().
• @inheritSection source_function Section title - унаследует один раздел с заголовком «Section title» от
source_function().
• @inheritDotParams - автоматически генерирует документацию по параметрам для ... общего случая,
когда вы переходите ... к другой функции.

13. Раздел справки по пакету
• Используйте функцию usethis::use_package_doc() для генерации файла R/{pkgname}-
package.R, который содердит документацию уровня пакета.
• Так же это хорошее место для хранения импорта, т.е. тегов @import и @importFrom.

14. СПАСИБО ЗА ВНИМАНИЕ