AGENT SKILL

write-roxygen-docs

Write roxygen2 documentation for R package functions, datasets, and classes. Covers all standard tags, cross-references, examples, and generating NAMESPACE entries. Follows tidyverse documentation style. Use when adding documentation to new exported functions, documenting internal helpers or datasets, documenting S3/S4/R6 classes and methods, or fixing documentation-related R CMD check notes.

License 许可
MIT
最近更新
2026-05-19
Stars
★ 10
Forks
2

01 前言 Front Matter

name
write-roxygen-docs
locale
caveman-lite
license
MIT
metadata
{ "tags": "r, roxygen2, documentation, namespace", "author": "Philipp Thoss", "domain": "r-packages", "version": "1.0", "language": "R", "complexity": "basic" }
translator
Julius Brussee homage — caveman
description
Write roxygen2 documentation for R package functions, datasets, and classes. Covers all standard tags, cross-references, examples, and generating NAMESPACE entries. Follows tidyverse documentation style. Use when adding documentation to new exported functions, documenting internal helpers or datasets, documenting S3/S4/R6 classes and methods, or fixing documentation-related R CMD check notes.
allowed-tools
Read Write Edit Bash Grep Glob
source_commit
82c77053
source_locale
en
translation_date
2026-05-03

03 SKILL.md 正文

Write Roxygen Documentation

Create complete roxygen2 documentation for R package functions, datasets, and classes.

When to Use

  • Adding documentation to a new exported function
  • Documenting internal helper functions
  • Documenting package datasets
  • Documenting S3/S4/R6 classes and methods
  • Fixing documentation-related R CMD check notes

Inputs

  • Required: R function, dataset, or class to document
  • Optional: Related functions for cross-referencing (@family, @seealso)
  • Optional: Whether the function should be exported

Procedure

Step 1: Write Function Documentation

Place roxygen comments directly above the function:

#' Compute the weighted mean of a numeric vector
#'
#' Calculates the arithmetic mean of `x` weighted by `w`. Missing values
#' in either `x` or `w` are handled according to the `na.rm` parameter.
#'
#' @param x A numeric vector of values.
#' @param w A numeric vector of weights, same length as `x`.
#' @param na.rm Logical. Should missing values be removed? Default `FALSE`.
#'
#' @return A single numeric value representing the weighted mean.
#'
#' @examples
#' weighted_mean(1:5, rep(1, 5))
#' weighted_mean(c(1, 2, NA, 4), c(1, 1, 1, 1), na.rm = TRUE)
#'
#' @export
#' @family summary functions
#' @seealso [stats::weighted.mean()] for the base R equivalent
weighted_mean <- function(x, w, na.rm = FALSE) {
  # implementation
}

Got: Complete roxygen block with title, description, @param for each parameter, @return, @examples, and @export.

If fail: If unsure about a tag, check ?roxygen2::rd_roclet. Common omission is @return, which is required by CRAN for all exported functions.

Step 2: Essential Tags Reference

Tag Purpose Required for export?
#' Title First line, one sentence Yes
#' Description Paragraph after blank line Yes
@param Parameter documentation Yes
@return Return value description Yes (CRAN)
@examples Usage examples Strongly recommended
@export Add to NAMESPACE Yes, for public API
@family Group related functions Recommended
@seealso Cross-references Optional
@keywords internal Mark as internal For non-exported docs

Got: All required tags for the function type are identified. Exported functions have @param, @return, @examples, and @export at minimum.

If fail: If a tag is unfamiliar, consult the roxygen2 documentation for usage and syntax.

Step 3: Document Datasets

Create R/data.R:

#' Example dataset of city temperatures
#'
#' A dataset containing daily temperature readings for major cities.
#'
#' @format A data frame with 365 rows and 4 variables:
#' \describe{
#'   \item{date}{Date of observation}
#'   \item{city}{City name}
#'   \item{temp_c}{Temperature in Celsius}
#'   \item{humidity}{Relative humidity percentage}
#' }
#' @source \url{https://example.com/data}
"city_temperatures"

Got: R/data.R contains roxygen blocks for each dataset with @format describing the structure and @source providing data provenance.

If fail: If R CMD check warns about undocumented datasets, ensure the quoted string (e.g., "city_temperatures") exactly matches the object name saved with usethis::use_data().

Step 4: Document the Package

Create R/packagename-package.R:

#' @keywords internal
"_PACKAGE"

## usethis namespace: start
## usethis namespace: end
NULL

Got: R/packagename-package.R exists with @keywords internal and the "_PACKAGE" sentinel. Running devtools::document() generates man/packagename-package.Rd.

If fail: If R CMD check reports a missing package documentation page, verify the file is named R/<packagename>-package.R and contains the "_PACKAGE" string.

Step 5: Handle Special Cases

Functions with dots in names (S3 methods):

#' @export
#' @rdname process
process.myclass <- function(x, ...) {
  # S3 method
}

Reusing documentation with @inheritParams:

#' @inheritParams weighted_mean
#' @param trim Fraction of observations to trim.
trimmed_mean <- function(x, w, na.rm = FALSE, trim = 0.1) {
  # implementation
}

No visible binding fix using .data pronoun:

#' @importFrom rlang .data
my_function <- function(df) {
  dplyr::filter(df, .data$column > 5)
}

Got: Special cases (S3 methods, inherited params, .data pronoun) are documented correctly. @rdname groups S3 methods together. @inheritParams reuses parameter docs without duplication.

If fail: If R CMD check warns about "no visible binding for global variable," add #' @importFrom rlang .data or use utils::globalVariables() as a last resort.

Step 6: Generate Documentation

devtools::document()

Got: man/ directory updated with .Rd files for each documented object. NAMESPACE regenerated with correct exports and imports.

If fail: Check for roxygen syntax errors. Common issues: unclosed brackets in \describe{}, missing #' prefix on a line, or invalid tag names. Run devtools::document() again after fixing.

Validation

  • [ ] Every exported function has @param, @return, and @examples
  • [ ] devtools::document() runs without errors
  • [ ] devtools::check() shows no documentation warnings
  • [ ] @family tags group related functions correctly
  • [ ] Examples run without errors (test with devtools::run_examples())

Pitfalls

  • Missing @return: CRAN requires all exported functions to document their return value
  • Examples that need internet/auth: Wrap in \dontrun{} with a comment explaining why
  • Slow examples: Use \donttest{} for examples that work but take too long for CRAN
  • Markdown in roxygen: Enable with Roxygen: list(markdown = TRUE) in DESCRIPTION
  • Forgetting to run devtools::document(): Man pages are generated, not hand-written

Related Skills

  • create-r-package - initial package setup including roxygen configuration
  • write-testthat-tests - test the functions you document
  • write-vignette - long-form documentation beyond function reference
  • submit-to-cran - documentation requirements for CRAN

04 同仓库更多 Skills

roohe
roohe/agentic-super-skills

zarr-python

Chunked N-D arrays for cloud storage. Compressed arrays, parallel I/O, S3/GCS integration, NumPy/Dask/Xarray compatible, for large-scale scientific computing pipelines.

★ 10
roohe
roohe/agentic-super-skills

youtube-downloader

Download and process YouTube content for research. Use when: downloading competitor videos for analysis; extracting audio for podcasts; getting transcripts for content repurposing; archiving webinars; research content curation

★ 10
roohe
roohe/agentic-super-skills

yc-pitch-deck

Create a compelling startup pitch deck that follows the structure proven to raise billions from top investors. Master the YC and Sequoia formats that get founders funded. Use when: **Fundraising** to create investor pitch decks; **YC application** to structure your narrative; **Demo Day prep** to craft your 2-minute pitch; **Angel investors** to communicate your opportunity; **Partnership pitches** to structure compelling asks

★ 10
roohe
roohe/agentic-super-skills

x-twitter-scraper

Use when the user needs X (Twitter) data or confirmation-gated X actions through Xquik: tweet search, user lookup, follower extraction, media download, monitoring, webhooks, MCP, SDKs, posting, likes, DMs, and profile updates. Requires a Xquik API key. Never ask for X login material.

★ 10
roohe
roohe/agentic-super-skills

write-vignette

Create R package vignettes using R Markdown or Quarto. Covers vignette setup, YAML configuration, code chunk options, building and testing, and CRAN requirements for vignettes. Use when adding a Getting Started tutorial, documenting complex workflows spanning multiple functions, creating domain-specific guides, or when CRAN submission requires user-facing documentation beyond function help pages.

★ 10
roohe
roohe/agentic-super-skills

write-validation-documentation

Write IQ/OQ/PQ validation documentation for computerized systems in regulated environments. Covers protocols, reports, test scripts, deviation handling, and approval workflows. Use when validating R or other software for regulated use, preparing for a regulatory audit, documenting qualification of computing environments, or creating and updating validation protocols and reports for new or re-qualified systems.

★ 10