扩展某个其他包的S4方法时,Rd文件名冲突

Question

实际问题

如何避免Rd文件名冲突

1. 一个S4通用及其方法(或多个)不必然全部在相同的包中定义(含有(部分的)自定义方法(一个或多个)软件包依赖于包含所述通用包)和
2. 使用roxygenize()包roxygen2生成实际的Rd文件？

roxygen2当通用及其方法分散在各个包中时,我不确定这是一个问题还是一个常见问题(如果遵循模块化编程风格,恕我直言肯定是一个真实的用例场景).

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

插图

在包中 pkga

假设在包中pkga你定义了一个通用方法foo,并且你已经提供了相应的roxygen代码来roxygenize()获取生成Rd文件:

#' 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()您的包时,foo-methods.Rd在man子目录中创建一个调用的文件,该子目录充当可能为此泛型方法创建的所有方法的引用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))
)

但是,如果package pkga提供了泛型,foo并且您决定在其他一些包中(例如pkgb)为类的类添加foo-method ,则会告诉您有关于Rd文件名和/或别名的名称冲突(如已经有一个路文件中):xcharacterR CMD checkfoo-methods.Rdpkga

在包中 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仍然被设置为fooroxygenizing时,因此错误仍然存在.除了手动编辑生成的Rd文件之外还有什么想法roxygenize()？

---

编辑2012-12-01

从启动赏金开始,实际问题可能会变得更宽泛:

我们如何针对Rd文件实现某种类型的"包间"检查和/或我们如何将分散在包中的S4方法帮助文件合并到一个单独的Rd文件中,以便为结束提供单个引用源-用户？

Answer 1

基本问题确实只是“氧化”。这就是为什么我从未见过这个问题。

虽然封装开发的氧化方法有充分的理由，但我仍然认为有一个很好的理由不这样做：

请求减少极端氧合作用

生成的帮助页面往往看起来非常无聊，不仅是自动生成的 *.Rd 文件，还有渲染的结果。例如

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

这是为什么？因为

1) 阅读和编辑 roxygen 注释比在 ESS 或 Rstudio 或（其他内置 *.Rd 支持的 IDE）中阅读和编辑 *.Rd 文件要“麻烦”得多，或者至少在视觉上没有回报

2）如果您使用该文档

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

你通常不会将写得好的 R 文档视为重要的东西（而是你的 R 代码，所有文档都只是注释:-)

所有这一切的结果是：人们更喜欢在小插图甚至博客、github 要点、youtube 视频等中编写有关其功能的文档，在创作时非常好，但与代码和绑定几乎分离变得过时和枯萎（因此，通过谷歌搜索误导你的用户）--> roxygen 将代码和文档放在同一个地方的最初动机完全被击败了。

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