在 R 包中记录重新导出的函数
Documenting re-exported functions in an R package
我正在将我的一个 R 程序包拆分为两个，因为它包含两组逻辑上不同的功能，其中一个比另一个更通用。然而，由于原始包相当受欢迎，并且至少被其他包所依赖，我不想破坏兼容性。
R 的命名空间系统提供了一种处理此问题的方法，即通过导入拆分包（RNifti), and then re-exporting them from the downstream package (which is RNiftyReg）中的函数。这样，第三方用户和包可以只加载 RNiftyReg，并且仍然可以看到现在实际属于 RNifti 的功能。此外，这些函数的文档仍然有效，因为 RNifti 命名空间与 RNiftyReg.
一起加载
然而，R CMD check 抱怨，因为重新导出的函数没有在 RNiftyReg 中记录。
所以我的问题是：这种情况下的最佳做法是什么？
我似乎有三个选择，none其中一个非常有吸引力。
- 通过要求新包
RNifti 与 RNiftyReg 一起加载来破坏现有代码，以便所有以前可用的功能可用。显然这是不可取的。
- 复制下游包中这些函数的所有文档，
RNiftyReg。这应该让每个人都满意，但维护起来很麻烦，如果包不总是一起更新，很容易不同步。
- 为
RNiftyReg 中的所有这些功能提供一个包罗万象的文档页面，指向 RNifti 中的完整文档。但这仍然需要与函数参数保持同步，并且它要求用户使用笨拙的 ?RNifti::somefun 语法来查看 "real" 文档。
有没有办法解决这个问题，或者像这样重新导出代码是不明智的？
我不会导入所有这些函数只是为了再次导出它们。对于这些事情，最合乎逻辑的做法似乎是使包 RNiftyReg 依赖于包 RNifti。
因此您在 DESCRIPTION 文件的 Depends 字段中添加：
Depends:
RNifti
要 100% 确保您使用 RNiftyReg 中的正确函数，您可以在代码中使用 :: 运算符调用它们，例如：
RNifti::aNiceFunction(arg1, arg2)
您可以将 RNifti 添加到 Depends 字段并仍然通过 NAMESPACE 文件导入包。如果您想让 RNifti 的功能可用于仅导入 RNiftyReg.
命名空间的包，则这是必要的
在那种情况下，您不会在 DESCRIPTION 文件的 Imports: 字段中提及它。正如手册所说，一个包应该只在两者之一中被提及。当你想要附加 RNifti 的命名空间时，你必须在 Depends 字段中提及它。
所以这实际上是您的第一个选项，但是以用户几乎不会注意到这种情况的方式完成。 library('RNiftyReg') 现在也会自动附加 RNifti。
从一些进一步的探索来看，R 版本 3.1.1 中添加的 \docType{import} 似乎是处理这种情况的最佳可用机制（如 this roxygen2 issue 中所述）。这似乎有效地表现得像我上面的第三个选项，但它的优点是不显式记录函数参数，因此它们不必保持同步。
似乎 roxygen2 语法像
#' @export
RNifti::xform
生成正确形式的.Rd文件，满足R CMD check。我以前没有使用过这种特殊的语法，这就是问题仍然悬而未决的原因。
我已经确认这适用于未经修改的第三方包，所以它看起来是最好的选择。
我正在将我的一个 R 程序包拆分为两个，因为它包含两组逻辑上不同的功能，其中一个比另一个更通用。然而，由于原始包相当受欢迎，并且至少被其他包所依赖，我不想破坏兼容性。
R 的命名空间系统提供了一种处理此问题的方法，即通过导入拆分包（RNifti), and then re-exporting them from the downstream package (which is RNiftyReg）中的函数。这样，第三方用户和包可以只加载 RNiftyReg，并且仍然可以看到现在实际属于 RNifti 的功能。此外，这些函数的文档仍然有效，因为 RNifti 命名空间与 RNiftyReg.
然而，R CMD check 抱怨，因为重新导出的函数没有在 RNiftyReg 中记录。
所以我的问题是：这种情况下的最佳做法是什么？
我似乎有三个选择，none其中一个非常有吸引力。
- 通过要求新包
RNifti与RNiftyReg一起加载来破坏现有代码，以便所有以前可用的功能可用。显然这是不可取的。 - 复制下游包中这些函数的所有文档，
RNiftyReg。这应该让每个人都满意，但维护起来很麻烦，如果包不总是一起更新，很容易不同步。 - 为
RNiftyReg中的所有这些功能提供一个包罗万象的文档页面，指向RNifti中的完整文档。但这仍然需要与函数参数保持同步，并且它要求用户使用笨拙的?RNifti::somefun语法来查看 "real" 文档。
有没有办法解决这个问题，或者像这样重新导出代码是不明智的？
我不会导入所有这些函数只是为了再次导出它们。对于这些事情，最合乎逻辑的做法似乎是使包 RNiftyReg 依赖于包 RNifti。
因此您在 DESCRIPTION 文件的 Depends 字段中添加：
Depends:
RNifti
要 100% 确保您使用 RNiftyReg 中的正确函数，您可以在代码中使用 :: 运算符调用它们，例如：
RNifti::aNiceFunction(arg1, arg2)
您可以将 RNifti 添加到 Depends 字段并仍然通过 NAMESPACE 文件导入包。如果您想让 RNifti 的功能可用于仅导入 RNiftyReg.
在那种情况下，您不会在 DESCRIPTION 文件的 Imports: 字段中提及它。正如手册所说，一个包应该只在两者之一中被提及。当你想要附加 RNifti 的命名空间时，你必须在 Depends 字段中提及它。
所以这实际上是您的第一个选项，但是以用户几乎不会注意到这种情况的方式完成。 library('RNiftyReg') 现在也会自动附加 RNifti。
从一些进一步的探索来看，R 版本 3.1.1 中添加的 \docType{import} 似乎是处理这种情况的最佳可用机制（如 this roxygen2 issue 中所述）。这似乎有效地表现得像我上面的第三个选项，但它的优点是不显式记录函数参数，因此它们不必保持同步。
似乎 roxygen2 语法像
#' @export
RNifti::xform
生成正确形式的.Rd文件，满足R CMD check。我以前没有使用过这种特殊的语法，这就是问题仍然悬而未决的原因。
我已经确认这适用于未经修改的第三方包，所以它看起来是最好的选择。