如何为自制R包创建roxygen2自定义标签？

1. 准备基础R包 #

先创建一个名为mycustompkg的R包，目录结构如下：

mycustompkg/
├── DESCRIPTION
├── NAMESPACE
└── R/

2. 添加自定义标签处理逻辑 #

在R/目录下新建roxygen_tags.R文件，写入以下代码：

#' @export
tag_information <- function(x) {
  # 解析@information标签后的文本内容
  roxygen2::tag("information", x)
}

#' @export
format.information <- function(x, ...) {
  # 定义标签内容在帮助文档里的显示样式
  paste0("\n**额外信息**: ", x$val, "\n")
}

关键规则说明：

• 解析标签的函数必须命名为tag_<你的标签名>，roxygen2会自动识别这个函数处理对应标签
• 格式化函数命名为format.<你的标签名>，负责把标签内容转换成帮助文档的可读格式，这里用加粗样式突出显示

3. 在函数文档中使用自定义标签 #

在R/目录下创建测试函数文件my_function.R：

#' 测试自定义标签的示例函数
#' @param x 输入的数值型参数
#' @information 这个函数仅用于演示自定义roxygen2标签，功能是返回输入值的2倍
#' @return 输入值乘以2的结果
#' @export
my_function <- function(x) {
  x * 2
}

4. 生成并查看结果 #

在R控制台运行以下命令生成帮助文档：

devtools::document()

之后运行?my_function查看帮助文档，就能看到额外信息板块显示了你在@information中填写的内容。

注意事项 #

• 确保包的DESCRIPTION文件中添加必要依赖：

  Imports:
    roxygen2 (>= 7.0.0)
  Suggests:
    devtools
  

• 修改标签处理逻辑后，必须重新运行devtools::document()才能更新文档
• 解析和格式化函数必须用@export导出，否则roxygen2无法识别

内容的提问来源于stack exchange，提问作者Patrick