R Academy · पाठ

roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण

स्वचालित दस्तावेज़ों के लिए @param, @return, @examples और @export टैग लिखें।

पाठ 2, कुल 4 में से13 चरण

roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण, CoddyKit पर R Academy का एक निःशुल्क पाठ है। यह 4 में से 2वाँ पाठ है। इस अध्ययन पथ के 3 तक कोई भी पाठ पूरा पढ़ना निःशुल्क है — इसके बाद CoddyKit PRO हर पाठ अनलॉक करता है, साथ ही अंतर्निर्मित कोड संपादक और चौबीसों घंटे एआई शिक्षक के साथ व्यावहारिक अभ्यास भी उपलब्ध कराता है। यह 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 टैग 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 को फिर से बनाएँ

शुरुआत निःशुल्क

एआई शिक्षक के साथ R सीखें — निःशुल्क

अपने ब्राउज़र में वास्तविक कोड लिखें और चलाएँ, चौबीसों घंटे एआई शिक्षक से तुरंत सहायता पाएँ, और वेब या ऐप पर वहीं से शुरू करें जहाँ आपने छोड़ा था।

पाठ्यक्रम: 43
पाठ: 159

निःशुल्क सीखना शुरू करें पूरा पाठ्यक्रम देखें

अक्सर पूछे जाने वाले प्रश्न

क्या “roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण” पाठ निःशुल्क है?

हाँ — R Academy अध्ययन पथ के 3 तक कोई भी पाठ, जिसमें “roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण” भी शामिल है, यहाँ वेब पर पूरा पढ़ना निःशुल्क है। इसके बाद CoddyKit PRO हर पाठ अनलॉक करता है, साथ ही अंतर्निर्मित कोड संपादक और चौबीसों घंटे एआई शिक्षक के साथ इंटरैक्टिव अभ्यास भी उपलब्ध कराता है। R Academy पाठ्यक्रम में कुल 4 पाठ शामिल हैं।

“roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण” में मैं क्या सीखूँगा?

स्वचालित दस्तावेज़ों के लिए @param, @return, @examples और @export टैग लिखें। आप ब्राउज़र में सीधे चलाए जाने वाले व्यावहारिक कोड के साथ R Academy का अभ्यास करते हैं, और पाठ पूरा करते समय 24/7 एआई ट्यूटर आपके प्रश्नों के उत्तर देता है।

क्या R Academy शुरू करने के लिए मुझे किसी अनुभव की आवश्यकता है?

पहले के अनुभव की आवश्यकता नहीं है। CoddyKit पर R Academy शुरुआती से लेकर उन्नत शिक्षार्थियों तक सभी के लिए व्यवस्थित किया गया है, इसलिए आप यहीं से या शुरुआत से सीखना शुरू कर सकते हैं और अपनी गति से आगे बढ़ सकते हैं। यह 4 में से 2वाँ पाठ है।

“roxygen2 से फ़ंक्शनों का दस्तावेज़ीकरण” पाठ पूरा करने में कितना समय लगता है?

CoddyKit का अधिकांश पाठ लगभग 5–10 मिनट में पूरा हो जाता है। हर पाठ छोटा और संवादात्मक है, इसलिए आप लगातार प्रगति करते हैं और वेब या ऐप पर वहीं से सीखना जारी रख सकते हैं जहाँ आपने छोड़ा था।

क्या मैं इस R Academy पाठ में कोड लिख और चला सकता हूँ?

हाँ। हर R Academy पाठ में एक अंतर्निर्मित कोड संपादक शामिल है, जिससे आप सीधे अपने ब्राउज़र में वास्तविक कोड लिख और चला सकते हैं और तुरंत एआई प्रतिक्रिया पा सकते हैं—स्थानीय सेटअप की आवश्यकता नहीं है।

इस पाठ्यक्रम के सभी पाठ

← R Academy पर वापस जाएँ