0Pricing
R Academy · Урок

Документирование функций с roxygen2

Пишите теги @param, @return, @examples и @export для автоматического создания документации

«Документирование функций с roxygen2» — бесплатный урок R Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения R Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс R Academy содержит 4 уроков всего.

Что такое roxygen2?

roxygen2 позволяет писать документацию R непосредственно над функцией в виде специально оформленных комментариев, начинающихся с #'. При запуске devtools::document() roxygen2 обрабатывает эти комментарии, автоматически создаёт файлы man/*.Rd и обновляет NAMESPACE.

Минимальный блок roxygen2

В простейшем блоке документации должны быть как минимум заголовок и описание. Первое предложение (до первой точки или пустой строки) становится заголовком. Последующие абзацы становятся описанием.

# R/add.R
#
# #' Add two numbers
# #'
# #' Computes the sum of x and y. Both arguments must be numeric.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

Теги @title и @description

Используйте явные теги @title и @description, когда соглашения с первым абзацем недостаточно — например, если заголовок должен отличаться от имени функции или описание состоит из нескольких абзацев.

# #' @title Safe Addition of Numeric Values
# #' @description
# #' Adds two numeric vectors element-wise.
# #' Returns NA where either input is NA.
# #' Useful for financial calculations where NA propagation matters.
# #'
# #' @export
# add <- function(x, y) {
#   x + y
# }

@param — документирование аргументов

#' @param name Description документирует один аргумент функции. Используйте одну строку @param для каждого аргумента. В описании следует указать ожидаемый тип и то, чем управляет аргумент.

# #' Add two numbers
# #'
# #' @param x A numeric vector. The first operand.
# #' @param y A numeric vector. The second operand. Must be the same length as x
# #'   or length 1 (recycled).
# #'
# #' @export
# add <- function(x, y) {
#   if (!is.numeric(x) || !is.numeric(y)) stop('x and y must be numeric')
#   x + y
# }

@return — документирование возвращаемого значения

#' @return Description описывает результат, возвращаемый функцией. Укажите тип, класс и структуру возвращаемого значения. Это требуется для отправки пакета в CRAN.

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of the same length as the longer of x or y,
# #'   containing the element-wise sums.
# #'
# #' @export
# add <- function(x, y) x + y

@examples — выполняемые примеры кода

#' @examples добавляет код, который отображается на справочной странице и выполняется командой R CMD check. Примеры должны выполняться менее чем за 5 секунд и не требовать внешних ресурсов (сети, файлов). Каждая строка — обычный код R, специальные префиксы не нужны.

# #' Add two numbers
# #'
# #' @param x A numeric vector.
# #' @param y A numeric vector.
# #' @return A numeric vector of element-wise sums.
# #' @examples
# #' add(1, 2)
# #' add(c(1, 2, 3), c(10, 20, 30))
# #' add(0, -5)
# #' @export
# add <- function(x, y) x + y

@export — открытие функций для пользователей

#' @export указывает roxygen2 добавить функцию в NAMESPACE, сделав её доступной пользователям Вашего пакета. Функции без @export являются внутренними: их можно вызывать внутри пакета, но не пользователям (без :::).

# Public function — exported:
# #' @export
# add <- function(x, y) x + y
#
# Internal helper — not exported:
# check_numeric <- function(x) {
#   if (!is.numeric(x)) stop('Expected numeric')
# }
#
# After devtools::document(), NAMESPACE will contain:
# export(add)
# but NOT check_numeric

@importFrom — импорт функций

#' @importFrom pkg fn1 fn2 импортирует указанные функции из пакета в Ваше пространство имён, чтобы Вы могли вызывать их без префикса pkg::. Используйте этот подход умеренно — явная запись pkg::fn() понятнее и не засоряет пространство имён.

# Option 1 — @importFrom (adds to NAMESPACE, no pkg:: needed):
# #' @importFrom stringr str_trim str_to_lower
# clean <- function(x) str_to_lower(str_trim(x))
#
# Option 2 — explicit :: (recommended for clarity):
# clean <- function(x) {
#   stringr::str_to_lower(stringr::str_trim(x))
# }
#
# Both work; prefer Option 2 to keep NAMESPACE minimal

Рабочий процесс devtools::document()

После редактирования комментариев roxygen2 вызовите devtools::document() (Ctrl+Shift+D), чтобы заново создать man/*.Rd и обновить NAMESPACE. Затем откройте справочную страницу с помощью ?add (после load_all()), чтобы убедиться, что она выглядит правильно.

# Full documentation cycle:
# 1. Edit roxygen2 comments in R/add.R
# 2. devtools::document()     # regenerate man/ and NAMESPACE
# 3. devtools::load_all()     # reload package
# 4. ?add                     # preview the help page
# 5. devtools::check()        # ensure no documentation errors

Документирование нескольких функций на одной странице

Используйте #' @rdname shared_name, чтобы объединить несколько связанных функций на одной справочной странице. Для основной функции укажите полный блок roxygen2, а для вторичных функций — только @rdname и @export.

# R/arithmetic.R
#
# #' Basic Arithmetic
# #' @param x,y Numeric vectors.
# #' @return A numeric vector.
# #' @examples
# #' add(1, 2); subtract(5, 3)
# #' @export
# add <- function(x, y) x + y
#
# #' @rdname add
# #' @export
# subtract <- function(x, y) x - y

Другие полезные теги

Дополнительные теги roxygen2 для полной документации:

  • #' @seealso \code{\link{other_fn}} — перекрёстная ссылка
  • #' @note — дополнительные примечания после описания
  • #' @author Name — автор функции
  • #' @keywords internal — скрывает функцию из индекса пакета, сохраняя её справочную страницу
  • #' @family group_name — объединяет связанные функции в справке
# #' Add two numbers
# #' @param x,y Numeric vectors.
# #' @return Numeric vector.
# #' @seealso \code{\link{subtract}} for the inverse operation.
# #' @family arithmetic
# #' @examples
# #' add(1, 1)
# #' @export
# add <- function(x, y) x + y

Быстрая проверка: тег @export

Что происходит с функцией в пакете R, у которой есть документация roxygen2, но НЕТ тега #' @export?

Итоги по документации roxygen2

Основные теги roxygen2 для полной документации пакета R:

  • #' @title / первая строка — заголовок функции
  • #' @description — подробное описание
  • #' @param name Description — документирование каждого аргумента
  • #' @return Description — описание возвращаемого значения
  • #' @examples \n code — выполняемые примеры (проверяются командой R CMD check)
  • #' @export — добавить в NAMESPACE (сделать функцию общедоступной)
  • #' @importFrom pkg fn — импортировать указанные функции
  • Запустите devtools::document(), чтобы заново создать man/ и NAMESPACE

Часто задаваемые вопросы

Урок «Документирование функций с roxygen2» бесплатный?

Да — полный текст урока «Документирование функций с roxygen2» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс R Academy, подпишись на CoddyKit PRO. Курс R Academy содержит 4 уроков всего.

Чему я научусь в уроке «Документирование функций с roxygen2»?

Пишите теги @param, @return, @examples и @export для автоматического создания документации Ты практикуешь R Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать R Academy?

Предыдущий опыт не требуется. R Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Документирование функций с roxygen2»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке R Academy?

Да. Каждый урок R Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Структура пакета с usethis и devtools
  2. Документирование функций с roxygen2
  3. Модульное тестирование с testthat
  4. Публикация в CRAN и сопровождение пакета
← Назад к R Academy