Agent-almanac write-roxygen-docs

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/write-roxygen-docs" ~/.claude/skills/pjt222-agent-almanac-write-roxygen-docs-c34e09 && rm -rf "$T"

manifest: i18n/zh-CN/skills/write-roxygen-docs/SKILL.md

source content

编写 Roxygen 文档

为 R 包函数、数据集和类创建完整的 roxygen2 文档。

适用场景

为新导出函数添加文档
记录内部辅助函数
记录包数据集
记录 S3/S4/R6 类及方法
修复文档相关的
```
R CMD check
```
注记

输入

必需：需要记录的 R 函数、数据集或类
可选：用于交叉引用的相关函数（
```
@family
```
、
```
@seealso
```
）
可选：函数是否应导出

步骤

第 1 步：编写函数文档

将 roxygen 注释直接放在函数上方：

#' 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
}

预期结果： 完整的 roxygen 块，包含标题、描述、每个参数的

@param

、

@return

、

@examples

以及

@export

。

失败处理： 若对某个标签不确定，查阅

?roxygen2::rd_roclet

。常见遗漏是

@return

，CRAN 要求所有导出函数必须包含此标签。

第 2 步：基本标签参考

标签	用途	导出时是否必需？
`#' Title`	首行，一句话描述	是
`#' Description`	空行后的段落	是
`@param`	参数文档	是
`@return`	返回值描述	是（CRAN 要求）
`@examples`	使用示例	强烈建议
`@export`	添加至 NAMESPACE	是，用于公开 API
`@family`	分组相关函数	建议
`@seealso`	交叉引用	可选
`@keywords internal`	标记为内部函数	用于不导出的文档

预期结果： 已识别适合该函数类型的所有必需标签。导出函数至少包含

@param

、

@return

、

@examples

和

@export

。

失败处理： 若某标签不熟悉，查阅 roxygen2 文档了解用法和语法。

第 3 步：记录数据集

创建

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"

预期结果：

R/data.R

包含每个数据集的 roxygen 块，

@format

描述数据结构，

@source

提供数据来源。

失败处理： 若

R CMD check

警告存在未记录的数据集，确保引号中的字符串（如

"city_temperatures"

）与

usethis::use_data()

保存的对象名称完全匹配。

第 4 步：记录包本身

创建

R/packagename-package.R

：

#' @keywords internal
"_PACKAGE"

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

预期结果：

R/packagename-package.R

存在，包含

@keywords internal

和

"_PACKAGE"

哨兵字符串。运行

devtools::document()

后生成

man/packagename-package.Rd

。

失败处理： 若

R CMD check

报告缺少包文档页，确认文件命名为

R/<packagename>-package.R

且包含

"_PACKAGE"

字符串。

第 5 步：处理特殊情况

带点号函数名（S3 方法）：

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

使用

@inheritParams

复用文档：

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

使用

.data

代词修复"无可见绑定"警告：

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

预期结果： 特殊情况（S3 方法、继承参数、

.data

代词）的文档处理正确。

@rdname

将 S3 方法合并，

@inheritParams

复用参数文档而无需重复。

失败处理： 若

R CMD check

警告"no visible binding for global variable"，添加

#' @importFrom rlang .data

，或作为最后手段使用

utils::globalVariables()

。

第 6 步：生成文档

devtools::document()

预期结果：

man/

目录已用每个文档对象的

.Rd

文件更新。NAMESPACE 已重新生成，包含正确的导出和导入条目。

失败处理： 检查 roxygen 语法错误。常见问题：

\describe{}

中括号未闭合、某行缺少

#'

前缀、标签名无效。修复后重新运行

devtools::document()

。

验证清单

每个导出函数均有
```
@param
```
、
```
@return
```
和
```
@examples
```
```
devtools::document()
```
运行无错误
```
devtools::check()
```
无文档相关警告
```
@family
```
标签正确分组相关函数
示例运行无错误（使用
```
devtools::run_examples()
```
测试）

常见问题

缺少
@return
：CRAN 要求所有导出函数记录返回值
示例需要网络或认证：用
```
\dontrun{}
```
包裹并注释说明原因
示例过慢：对能运行但对 CRAN 而言耗时过长的示例使用
```
\donttest{}
```
roxygen 中使用 Markdown：在 DESCRIPTION 中启用
```
Roxygen: list(markdown = TRUE)
```
忘记运行
devtools::document()
：man 页面是生成的，而非手写的

Agent-almanac write-roxygen-docs

编写 Roxygen 文档

适用场景

输入

步骤

第 1 步：编写函数文档

第 2 步：基本标签参考

第 3 步：记录数据集

第 4 步：记录包本身

第 5 步：处理特殊情况

第 6 步：生成文档

验证清单

常见问题

相关技能