roxygen2로 함수 문서화
자동 문서 생성을 위해 @param, @return, @examples 및 @export 태그를 작성합니다.
roxygen2로 함수 문서화은(는) CoddyKit의 무료 R Academy 강의입니다. 이것은 4개 중 2번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 R Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. R Academy 강의에는 총 4개의 강의가 포함되어 있습니다.
roxygen2란 무엇입니까
roxygen2를 사용하면 함수 바로 위에 #'로 시작하는 특수한 형식의 주석으로 R 문서를 작성할 수 있습니다. devtools::document()를 실행하면 roxygen2가 이 주석을 분석하여 man/*.Rd file을 생성하고 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 line을 하나씩 사용하십시오. 설명에는 예상되는 type과 해당 인수가 제어하는 내용을 밝혀야 합니다.
# #' 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은 함수가 반환하는 내용을 설명합니다. 반환 값의 type, class, 구조를 명시하십시오. 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초 이내에 완료되어야 하며 외부 리소스(네트워크, file)를 필요로 해서는 안 됩니다. 각 line은 일반적인 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 minimaldevtools::document() 작업 흐름
roxygen2 주석을 편집한 후 devtools::document()(Ctrl+Shift+D)를 호출하여 man/*.Rd를 다시 생성하고 NAMESPACE를 업데이트하십시오. 그런 다음 load_all()을 실행한 뒤 ?add로 도움말 페이지를 확인하여 올바르게 표시되는지 검증하십시오.
# 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 태그가 NO인 함수에는 어떤 일이 일어납니까?
roxygen2 문서화 복습
완전한 R 패키지 문서화를 위한 핵심 roxygen2 태그는 다음과 같습니다.
#' @title/ 첫 줄 — 함수 제목#' @description— 자세한 설명#' @param name Description— 각 인수 문서화#' @return Description— 반환 값 설명#' @examples \n code— 실행 가능한 예제(R CMD check에서 검사)#' @export— NAMESPACE에 추가(함수를 공개 함수로 만듦)#' @importFrom pkg fn— 특정 함수 가져오기devtools::document()를 실행하여 man/과 NAMESPACE를 다시 생성합니다
AI 튜터와 함께 R을(를) 배우세요 — 무료
브라우저에서 실제 코드를 작성하고 실행하며, 24/7 AI 튜터로부터 즉각적인 도움을 받고, 웹이나 앱에서 중단한 부분부터 계속 학습하세요.
- 코스
- 43
- 레슨
- 159
자주 묻는 질문
“roxygen2로 함수 문서화” 강의는 무료인가요?
네 — “roxygen2로 함수 문서화” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 R Academy 강의 전체를 잠금 해제할 수 있습니다. R Academy 강의에는 총 4개의 강의가 포함되어 있습니다.
“roxygen2로 함수 문서화”에서 뭘 배우나요?
자동 문서 생성을 위해 @param, @return, @examples 및 @export 태그를 작성합니다. 브라우저에서 직접 실행하는 실습 코드로 R Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.
R Academy을(를) 시작하는 데 경험이 필요한가요?
사전 경험은 필요하지 않습니다. CoddyKit의 R Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 2번째 강의입니다.
“roxygen2로 함수 문서화” 강의는 얼마나 걸리나요?
대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.
이 R Academy 강의에서 코드를 작성하고 실행할 수 있나요?
네. 모든 R Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.