R文档:@family标记不起作用

zdwk9cvp  于 2023-04-09  发布在  其他
关注(0)|答案(1)|浏览(113)

我正在写一个R包,我想在函数文档之间包含交叉引用。
在文档here之后,有一个章节专门讨论了这一点:

交叉引用

有两个标签可以让人们更容易地浏览您的文档:@seealso@family . [...]如果你有一个相关函数的家族,你可以使用@family {family}来交叉引用家族中的每个函数。一个函数可以是多个家族的成员。
对于sum(),这可能看起来像:

#' @family aggregations
#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and
#'   [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.

默认情况下,@family {family}将生成另请参阅文本“Other {family}:”,因此@family名称应该是复数(即“model building helpers”而不是“model building helper”)。您可以通过在man/roxygen/meta.R中提供rd_family_title列表来覆盖默认标题:

rd_family_title <- list(
 aggregations = "Aggregation functions"
)

所以,我写了我的函数的文档如下:

#' My foo function
#'
#' Does something with my data.
#'
#' Lorem ipsum.
#'
#' @param .data A data frame.
#' @return My processed data.
#' @usage
#' my_foo_function(.data)
#' @family {a_family}
#' @family {another_family}
#' @export
my_foo_function <- function(.data) {
# Some code
}

(我用这种方式写了大约9个函数)
我也写了这个meta.R文件:

rd_family_title <- list(
  a_family = "A family of functions",
  another_family = "Another family of functions"
)

保存在这里:[package project path]/roxygen/man/meta.R(同样,遵循文档)。
但是,当我运行document()函数(以构建.Rd文件)时,我得到以下警告:

document()
## Updating my_package documentation
## Writing NAMESPACE
## Warning messages:
## 1: Unknown Roxygen options a_family, another_family.
## Supported options: roclets, load, old_usage, markdown, r6, package

在浏览文档时,我看到了这样的内容:
[...]

参见

其他a_family:bar(),baz()其他another_family:spam(),eggs()
(我用@family a_family修改了@family {a_family},得到了相同的结果。
那么...我遗漏了什么?rd_family_title列表应该在哪里?为什么Roxy不能用我定义的标题替换“其他...”的东西?
一些附加信息:

  • R版本:3.6.0,在CentOs 7上运行,使用Rstudio
  • Roxygen2版本:7.0.2
  • devtools版本:2.2.1
gojuced7

gojuced71#

当你查阅文档时,文档中的man/roxygen/meta.R示例是错误的。缺少第一个列表级别。
在您的情况下,它应该是:

list(
  rd_family_title = list(a_family = "A family of functions",
                         another_family = "Another family of functions")
)

代码中还有一个遗漏,导致roxygen2的rd_family_title选项无法识别。所有这些问题都已在PR 1078中修复,从roxygen2 7.1.1开始包含。

相关问题