当扩展其他包的S4方法时，Rd文件名会发生冲突
实际的问题
如何避免Rd文件名称冲突
- 一个S4generics和它的方法不一定全都在同一个包中定义（包含（一些）定制方法的包依赖于包含generics的包）
- 使用
roxygenize()包中的roxygenize()生成实际的Rd文件？
我不确定这是一个roxygen2问题还是一个普通的问题，当generics和它的方法分散在不同的包（如果你遵循一个模块化的编程风格，一般来说，恕我直言，一定是一个现实的用例场景）。
build议如何处理这些情况？
插图
在包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的文件被创build在man子目录中，作为可能为这个generics方法创build的所有方法的参考Rd文件。 到现在为止还挺好。 如果这个通用的所有方法也是你的包的一部分，一切都很好。 例如，这个roxygen代码将确保将文档添加到foo-methods.Rd用于foo-methods.Rd的ANY方法：
#' @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的generics，并且你决定在其他一些包（比如pkgb ）中添加一个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* ），但是当roxygenizing时仍然将\title和\name设置为foo ，因此错误仍然存在。 除了手动编辑由roxygenize()生成的Rd文件之外的任何想法？
编辑2012-12-01
从开始赏金来看，实际的问题可能会略微宽泛些：
我们如何才能对Rd文件实现某种“内部包”检查，以及/或者我们如何将分散在不同包中的S4方法帮助文件整合到一个Rd文件中，以便为结尾提供单一的参考源-用户？
基本的问题确实是“好氧化”。 这就是为什么我从来没有看到这个问题。
虽然有很好的理由来包装发展的roxygenizing，我仍然有一个很好的理由不去那里：
请求更less的极度roxygenation
由此产生的帮助页面往往看起来非常无聊，不仅是自动生成的* .Rd文件，而且渲染的结果。 例如
- 例子往往是最小的，不包含评论，往往没有很好的格式（使用空间，/新行/ ..）
- math问题很less通过\ eqn {}或\ deqn {}解释。
- \ describe {..}和类似的高级格式化很less使用
这是为什么？ 因为
1）读取和编辑roxygen注释比在ESS或Rstudio或（其他IDE内置有* .Rd支持的IDE）中的阅读和编辑* .Rd文件更加“繁琐”，或者至less在视觉上没有吸引力。
2）如果你使用的文件
是在你的包构build/检查结束时自动生成的东西
你通常倾向于不考虑写好R文档作为重要的东西（而是你的R代码，所有的文档只是一个注释:-)
所有这一切的结果是：人们更喜欢在小插曲，甚至是博客，github gists，youtubevideo，或者…在创作时非常好的地方写文档，但是与代码和界限过时和枯萎（因此，通过谷歌search误导你的使用） – >在同一地点有代码和文档的roxygen的原始动机全部被打败。
我喜欢roxygen，并在创build新function时广泛使用它，只要我的函数不在包中， 或者不被导出，我就会保留并维护它。 一旦我决定导出它，我运行一次（相当于）的roxygenize（）的ESS，并从此承担维护格式良好的* .Rd文件的小额外负担 ，包含它自己的评论（对于我作为作者） ，有很多很好的例子，有它自己的修改控制（git / svn / …）历史等等。
我设法为另一个软件包中定义的generics的S4方法生成NAMESPACE和* .Rd文件。
它采取了以下步骤：
-
手动创buildNAMESPACE作为已知roxygen2错误的解决方法。
用手写一个NAMESPACE并不是那么难！
在RStudio中通过roxygen2closuresNAMESPACE代：
Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE. -
导入包含generic的包并使用exportMethods导出S4方法 。
-
为每个S4方法分别写入roxygen2文档。 不要结合roxygen2文档（正如我通常为同一个通用的不同方法）。
-
将明确的roxygen标签@title和@description添加到S4方法的roxygen文档中。 明确地写@description，即使它的值和@title一样。
这使它对我有用。
