如何在Roxygen文档中复用条目描述？

方法1：使用Roxygen2模板系统（推荐） #

Roxygen2的模板系统支持将重复的文档片段单独定义，再在需要的地方引用，完美解决feature_ID这类重复描述的问题。

步骤1：创建模板文件 #

在R包根目录下新建man-roxygen文件夹（无则创建），在其中新建模板文件feature_id_desc.R，内容如下：

#' \item{\code{feature_ID}}{character, a very carefully defined description}

步骤2：在文档中引用模板 #

在需要插入feature_ID描述的位置，用@template标签调用模板：

内置数据框文档（R/data.R）

#' @name OBJ_1
#' @title Object 1
#' @format A data frame with 401 rows and 6 variables:
#' \describe{
#'   @template feature_id_desc
#'   \item{\code{col1}}{double, blah}
#'   \item{\code{col2}}{integer, blah}
#'   \item{\code{col3}}{character, blah}
#'   \item{\code{col4}}{integer, blah}
#'   \item{\code{col5}}{character, blah}
'}   
"OBJ_1"

#' @name OBJ_2
#' @title Object 2
#' @format A data frame with 333 rows and 5 variables:
#' \describe{
#'   @template feature_id_desc
#'   \item{\code{col6}}{double, blah}
#'   \item{\code{col7}}{integer, blah}
#'   \item{\code{col8}}{character, blah}
#'   \item{\code{col9}}{integer, blah}
'}   
"OBJ_2"

函数返回值文档

#' Some function 
#'
#' @return data frame with one row per feature:
#' \describe{
#'   @template feature_id_desc
#'   \item{\code{colx}}{blah}
#'   \item{\code{coly}}{blah}
#' }
#' 
#' @export
#' 
myFunction = function(){
  # do stuff
  return(df)
}

注意：@template后直接写模板文件名（无需.R后缀）即可。

方法2：自定义R函数生成描述片段，结合动态插入 #

如果需要更灵活的动态生成逻辑，可以写一个内部函数返回feature_ID的描述文本，再插入到文档中。

步骤1：定义生成函数 #

在包内的工具文件（如R/utils_doc.R）中定义：

#' @keywords internal
get_feature_id_desc <- function() {
  return("\\item{\\code{feature_ID}}{character, a very carefully defined description}")
}

步骤2：在文档中插入 #

通过动态代码插入片段：

#' Some function 
#'
#' @return data frame with one row per feature:
#' \describe{
#'   `r get_feature_id_desc()`
#'   \item{\code{colx}}{blah}
#'   \item{\code{coly}}{blah}
#' }
#' 
#' @export
#' 
myFunction = function(){
  # do stuff
  return(df)
}

此方法需注意转义字符处理，适合需要动态调整描述的场景，优先推荐模板系统。

方法3：使用@inherit标签（适用于大面积文档复用） #

如果某份文档的大部分内容与另一份重复，可通过@inherit继承基础文档，再补充差异内容，适合整份文档的复用场景：

#' @name OBJ_2
#' @title Object 2
#' @inheritParams OBJ_1
#' @format A data frame with 333 rows and 5 variables:
#' \describe{
#'   @template feature_id_desc
#'   \item{\code{col6}}{double, blah}
#'   \item{\code{col7}}{integer, blah}
#'   \item{\code{col8}}{character, blah}
#'   \item{\code{col9}}{integer, blah}
'}   
"OBJ_2"

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