การจัดทำเอกสารฟังก์ชันด้วย roxygen2
เขียนแท็ก @param, @return, @examples และ @export เพื่อสร้างเอกสารโดยอัตโนมัติ
การจัดทำเอกสารฟังก์ชันด้วย roxygen2 เป็นบทเรียน R Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 2 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 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 ใหม่
เรียนรู้ R ด้วย AI tutor — ฟรี
เขียนและเรียกใช้โค้ดจริงในเบราว์เซอร์ของคุณ รับความช่วยเหลือทันทีจาก AI tutor 24/7 และเรียนรู้ต่อจากที่คุณหยุดบนเว็บหรือในแอป
- คอร์ส
- 43
- บทเรียน
- 159
คำถามที่พบบ่อย
บทเรียน “การจัดทำเอกสารฟังก์ชันด้วย roxygen2” ฟรีหรือไม่
ใช่ — ข้อความเต็มของ “การจัดทำเอกสารฟังก์ชันด้วย roxygen2” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส R Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส R Academy มีบทเรียนทั้งหมด 4 บทเรียน
คุณจะเรียนรู้อะไรในบทเรียน “การจัดทำเอกสารฟังก์ชันด้วย roxygen2”
เขียนแท็ก @param, @return, @examples และ @export เพื่อสร้างเอกสารโดยอัตโนมัติ คุณปฏิบัติ R Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 24/7 ตอบคำถามของคุณขณะที่คุณไปผ่านบทเรียน
คุณต้องมีประสบการณ์ก่อนที่จะเริ่มเรียน R Academy หรือไม่
ไม่จำเป็นต้องมีประสบการณ์มาก่อน R Academy บน CoddyKit ออกแบบมาสำหรับผู้เริ่มต้นไปจนถึงผู้เรียนขั้นสูง คุณสามารถเริ่มต้นที่นี่หรือเริ่มจากตัวแรกและเรียนด้วยความเร็วของคุณเอง นี่คือบทเรียนที่ 2 จากทั้งหมด 4 บทเรียน
บทเรียน “การจัดทำเอกสารฟังก์ชันด้วย roxygen2” ใช้เวลานานแค่ไหน
บทเรียน CoddyKit ส่วนใหญ่ใช้เวลาประมาณ 5–10 นาที แต่ละบทเรียนจึงสั้นและเป็นแบบโต้ตอบ คุณสามารถก้าวหน้าอย่างต่อเนื่องและกลับมาเรียนต่อจากตรงที่เพิ่งหยุดบนเว็บและแอปได้เลย
ฉันเขียนและรันโค้ดในบทเรียน R Academy นี้ได้ไหม
ได้ บทเรียน R Academy ทุกบทมีตัวแก้ไขโค้ดในตัว คุณจึงเขียนและรันโค้ดจริงได้เลยในเบราว์เซอร์ และได้รับข้อเสนอแนะจาก AI ในทันที — ไม่ต้องติดตั้งในเครื่องของคุณ
บทเรียนทั้งหมดในหลักสูตรนี้
- โครงสร้างแพ็กเกจด้วย usethis และ devtools
- การจัดทำเอกสารฟังก์ชันด้วย roxygen2
- การทดสอบหน่วยด้วย testthat
- การส่งแพ็กเกจไปยัง CRAN และการบำรุงรักษา