Question

实际问题

时如何避免Rd文件名冲突

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

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

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

插图

包pkga

假设在包pkga中您定义了一个通用方法foo，并且您已经提供了roxygenize()选择的相应的roxygen代码来生成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文件。到现在为止还挺好。如果这个通用的所有方法也是你的包的一部分，一切都很好。例如，此漫游代码将确保将文档添加到foo-methods.Rd的{{1}} - 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）中为{{1}添加pkgb - 方法如果是foo类，那么x将告诉您有关于Rd文件名和/或别名的名称冲突（因为已存在Rd文件character R CMD check）：

包foo-methods.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？

编辑2012-12-01

鉴于开始赏金，实际问题可能会稍微扩大一点：

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

Answer 1

基本问题确实是＆＃34; roxygenize＆＃34; -only。这就是我从未见过这个问题的原因。

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

请求更少极端的氧合作用

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

示例通常很少，不包含注释，通常格式不正确（使用空格，/新行/..)
很少通过\ eqn {}或\ deqn {}
\ describe {..}和类似的高级格式很少使用

为什么？因为

1）阅读和编辑roxygen评论是非常多的＆＃34;繁琐＆＃34;或至少在视觉上没有收获而不是在ESS或Rstudio中读取和编辑* .Rd文件或（内置* .Rd支持的其他IDE）

2）如果您使用该文档

是在您的包构建/检查
结束时自动生成的内容

你通常倾向于不把考虑好的R文档作为重要的东西（而是你的R代码，所有文档都只是评论： - ）

所有这一切的结果：人们更喜欢在小插图甚至博客，github gists，youtube视频或者...中创作关于他们的功能的文档，在创作时它非常好，但是几乎脱离了代码并且必然会过时和枯萎（因此，通过谷歌搜索误导你的useRs） - ＆GT;在同一个地方拥有代码和文档的roxygen的原始动机完全被打败了。

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

Answer 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文档（正如我通常对同一通用的不同方法所做的那样）。
将明确的roxygen标签@title和@description添加到S4方法的roxygen文档中。明确写@description，即使它的值与@title相同。

这对我有用。

请求更少极端的氧合作用

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

实际问题

插图

尽职调查

编辑2012-12-01

2 个答案: