我正在写一个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
1条答案
按热度按时间gojuced71#
当你查阅文档时,文档中的
man/roxygen/meta.R
示例是错误的。缺少第一个列表级别。在您的情况下,它应该是:
代码中还有一个遗漏,导致roxygen2的
rd_family_title
选项无法识别。所有这些问题都已在PR 1078中修复,从roxygen2 7.1.1开始包含。