如何在 Roxygen2 中指示整理顺序？答案

【问题标题】：How do I indicate collate order in Roxygen2?如何在 Roxygen2 中指示整理顺序？
【发布时间】：2013-09-03 20:07:18
【问题描述】：

使用 roxygen2 文档和 devtools document 函数会自动在包DESCRIPTION 中生成Collate: 字段，无论是否需要按特定顺序加载包库文件。

我正在开发一个包含一堆 S4 方法的包，并希望确保在使用它们的任何方法或其他类之前加载类定义，我知道我可以使用 Collate 列表来完成，但我'不知道如何在 roxygen2 文档格式中指出这一点。

roxygen2 manual 引用了@include 标记，但看起来它实际上可能只是在文档中包含代码，例如，通过@examples 标记添加外部示例。这可以用于指定方法的整理顺序吗？

【问题讨论】：

如果 collate 字段已经在DESCRIPTION中，roxygen2不会生成它。所以我会说你必须做出你想要的顺序，它应该得到尊重。（我认为；因此评论与答案）。
很高兴知道我的@import 解释是否正确。如果有一个函数从文件依赖项列表中计算出整理顺序，而不是手动计算出来，这当然会很好。
import 用于导入包。这类似于在 Depends 部分列出一个包，只是它更干净，因为它不会污染用户的命名空间。
让我说@importfrom 更好，因为它避免了命名冲突。
哎呀，我的意思是说@include 是我不明白的标签，抱歉打错了。上面的文字已更改。 @include 标签是怎么回事？它与 Collate 排序有什么关系？

【解决方案1】：

包含标签用于说明一个文件需要另一个文件才能工作。（名字包括可能不是最好的选择，但生活就是这样）。如果您想确保在文件 A 之前加载文件 B，请确保在 A 中使用 @include B。Roxygen 将负责排序整理字段以满足您的限制。

【讨论】：

【解决方案2】：

我刚刚发现，如果您在 R 文件的顶部添加 @include 语句，它将干扰下一个 roxygen2 文档块，除非您在它后面加上 NULL 例如

#' @include something.R
NULL

#' Documenting a function
#'
#" It does something...
#'
#' @param ...
#'

【讨论】：

我发现在任何 roxygen 块的开头包含 #' @include file-with-class-definitions.R 很有用，该块定义了与类定义不同的文件中的 S4 类的方法。这样，您肯定会在定义方法之前定义类，即使包含类定义的文件按字母顺序排列在定义方法的文件名之前。安全总比后悔好！