扩展某些其他包的 S4 方法时 Rd 文件名冲突答案

【问题标题】：Rd file name conflict when extending a S4 method of some other package扩展某些其他包的 S4 方法时 Rd 文件名冲突
【发布时间】：2012-10-19 17:29:19
【问题描述】：

实际问题

如何避免Rd文件名冲突

S4 泛型及其方法不一定都定义在同一个包中（包含（某些）自定义方法的包取决于包含泛型的包）和
使用roxygen2 包中的roxygenize() 来生成实际的Rd 文件？

我不确定这是roxygen2 问题还是泛型及其方法分散在包中时的常见问题（恕我直言，如果您遵循模块化编程风格）。

处理这些情况的推荐方法是什么？

插图

包装内pkga

假设您在包pkga 中定义了一个通用方法foo，并且您提供了roxygenize() 用来生成Rd 文件的相应roxygen 代码：

#' Test function
#' 
#' Test function.
#' 
#' @param ... Further arguments.
#' @author Janko Thyson \email{janko.thyson@@rappster.de}
#' @example inst/examples/foo.R
#' @docType methods
#' @rdname foo-methods
#' @export

setGeneric(
    name="foo",
    signature=c("x"),
    def=function(
         x,  
        ...
    ) {
    standardGeneric("xFoo")       
    }
)

当roxygenizing() 您的包时，会在man 子目录中创建一个名为foo-methods.Rd 的文件，该文件用作可能为此通用方法创建的所有方法的参考Rd 文件。到目前为止，一切都很好。如果此泛型的所有方法也是您的包的一部分，那么一切都很好。例如，此 roxygen 代码将确保将文档添加到 foo-methods.Rd 以用于 ANY-foo 的方法：

#' @param x \code{ANY}.
#' @return \code{TRUE}.
#' @rdname foo-methods
#' @aliases foo,ANY-method
#' @export

setMethod(
    f="foo", 
    signature=signature(x="ANY"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(TRUE)
    }, options=list(suppressAll=TRUE))
)

但是，如果包pkga 提供了foo 的泛型，并且您决定在其他一些包（例如pkgb）中为x 添加一个foo 方法x 属于character 类，那么R CMD check 会告诉您 Rd 文件名和/或别名存在名称冲突（因为在 pkga 中已经存在 Rd 文件 foo-methods.Rd）：

包装内pkgb

#' @param x \code{character}.
#' @return \code{character}.
#' @rdname foo-methods
#' @aliases foo,character-method
#' @export

setMethod(
    f="foo", 
    signature=signature(x="character"), 
    definition=cmpfun(function(
        x,
        ...
    ) {
    return(x)
    }, options=list(suppressAll=TRUE))
)

更准确地说，这是抛出/写入文件00install.out的错误

Error : Q:/pkgb/man/foo-methods.Rd: Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'pkgb'

尽职调查

我尝试将@rdname 和@aliases 的值更改为foo_pkgb*（而不是foo*），但\title 和\name 在roxygenizing 时仍设置为foo，因此出现错误遗迹。 除了手动编辑 roxygenize() 生成的 Rd 文件之外还有什么想法吗？

编辑 2012-12-01

鉴于开始赏金，实际问题可能会变得更广泛：

我们如何对 Rd 文件实施某种“包间”检查和/或如何将分散在包中的 S4 方法帮助文件合并到一个 Rd 文件中，以便呈现单个最终用户的参考来源？

【问题讨论】：

标签： r generics package s4 roxygen2

【解决方案1】：

基本问题确实是“roxygenize”-only。这就是为什么我从未见过这个问题。

虽然包开发的 roxygenizing 方法有充分的理由，我仍然看到一个很好的理由不去那里：

请求减少极端的氧化作用

生成的帮助页面看起来非常乏味，不仅是自动生成的 *.Rd 文件，还有呈现的结果。例如

示例通常很少，不包含 cmets，通常格式不正确（使用空格、/换行符/..）
数学问题很少通过 \eqn{} 或 \deqn{} 来解释
\describe{ .. } 和类似的高级格式很少使用

这是为什么呢？因为

1) 阅读和编辑 roxygen cmets 远不止这些 “麻烦”或至少在视觉上没有回报而不是在 ESS 或 Rstudio 或（其他内置 *.Rd 支持的 IDE）中读取和编辑 *.Rd 文件

2) 如果你使用过那个文档

是在你的包构建/检查结束时自动生成的东西

您通常不会将编写良好的 R 文档视为重要的东西（而是您的 R 代码，所有文档只是评论:-)

所有这一切的结果：人们更喜欢在小插曲甚至博客、github 要点、youtube 视频或...中编写有关其功能的文档，这些文档在创作时非常好，但几乎与代码分离，并且必然会过时和枯萎（因此，通过 Google 搜索误导您的用户） --> roxygen 将代码和文档放在同一个地方的最初动机完全被打败了。

我喜欢 roxygen，并在我创建新功能时广泛使用它... 只要我的函数不在包中，我就会保留并维护它，或没有导出。一旦我决定导出它，我运行（相当于 ESS）roxygenize() 一次从那时起，承担维护格式良好的 *.Rd 文件的额外负担，包含自己的 cmets（对于我作为作者），有许多很好的例子，有自己的修订控制（ git / svn / ...) 历史记录等

【讨论】：

非常感谢您的回答，马丁！我完全明白你的意思。然而，我不同意你论证的几个方面（我将在下周更详细地解释它们）。我非常乐意与您讨论这个问题！

【解决方案2】：

我设法为 S4 方法生成 NAMESPACE 和 *.Rd 文件，用于在我的另一个包中定义的泛型。

我采取了以下步骤：

手动创建 NAMESPACE 作为known roxygen2 bug 的解决方法。

手写一个 NAMESPACE 一点也不难！

在 RStudio 中关闭 roxygen2 生成的 NAMESPACE：
```
Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.
```
import the package containing the generic and export the S4 methods using exportMethods.
为每个 S4 方法编写单独的 roxygen2 文档。不要合并 roxygen2 文档（就像我通常对相同泛型的不同方法所做的那样）。
在 S4 方法的 roxygen 文档中添加显式 roxygen 标签 @title 和 @description。显式编写@description，即使它的值与@title 相同。

这使它对我有用。

【讨论】：