扩展其他包的 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))
)

但是，如果包pkga提供 foo 的通用并且您决定在其他某个包(例如 pkgb )中添加 foo -x的方法属于类(class)character ，然后R CMD check会告诉您 Rd 文件名和/或别名存在名称冲突(因为 foo-methods.Rd 中已存在 Rd 文件 pkga ):

包装内 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仍然设置为foo当氧合时，错误仍然存​​在。 除了手动编辑 Rd 文件由 roxygenize() 生成的任何想法？

<小时/>

编辑2012-12-01

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

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

Answer 1

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

虽然封装开发采用氧化方法有充分的理由，我仍然认为有一个很好的理由不去那里:

请求减少极端氧化

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

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

这是为什么呢？因为

1) 阅读和编辑 roxygen 评论的意义远不止于此 “麻烦”或至少在视觉上没有返回 与在 ESS 或 Rstudio 或(其他内置 *.Rd 支持的 IDE)中读取和编辑 *.Rd 文件相比

2) 如果您使用该文档

is the thing that's automatically generated at the end of your package building/checking

您通常不认为写得好的 R 文档很重要(而是你的 R 代码，所有文档都只是一条注释:-)

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

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