R文档：@family标记无效。

Question

R文档：@family标记无效。

4

我正在编写一个R包，并希望在函数文档之间包含交叉引用。

按照这里的文档，有一个专门讨论此事的部分:

Cross-references

There are two tags that make it easier for people to navigate around your documentation: @seealso and @family. [...] If you have a family of related functions, you can use @family {family} to cross-reference each function to every other function within the family. A function can be a member of multiple families.

For sum(), this might look like:
#' @family aggregations
#' @seealso [prod()] for products, [cumsum()] for cumulative sums, and
#'   [colSums()]/[rowSums()] marginal sums over high-dimensional arrays.
By default @family {family}, will generate the see also text “Other {family}:”, so the @family name should be plural (i.e., “model building helpers” not “model building helper”). You can override the default title by providing a rd_family_title list in man/roxygen/meta.R:
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"
)

这个保存在这里：[包项目路径]/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 列表应该在哪里？为什么Roxygen无法用我定义的标题替换那个“其他…”的东西？

一些附加信息：

R版本：3.6.0，运行在CentOs 7上，并使用Rstudio
Roxygen2版本：7.0.2
devtools版本：2.2.1

- Barranka

man/roxygen/meta.R 应该返回一个列表，其中一个元素是 rd_family_title，请参见此处。这应该可以消除警告。但对我来说仍然不起作用。 - alan ocallaghan

1

实际上我错了，当我制作列表时，我只是使用了<-而不是=。看起来这可能目前已经出现了问题，因为load_options_meta仅在全局范围内执行，而rd_family_title不是允许的选项，请参见：https://github.com/r-lib/roxygen2/search?q=load_options_meta&unscoped_q=load_options_meta - alan ocallaghan

@alanocallaghan 谢谢...看起来它坏了 :( 很遗憾，如果它能工作就太棒了。 - Barranka

1

我建议在代码库上开一个问题，这样要么问题会被解决，要么他们会告诉你你做错了什么。 - alan ocallaghan

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Salim B · Accepted Answer

文档中的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开始包含。