扩展某个其他包的S4方法时，Rd文件名会发生冲突 [英] Rd file name conflict when extending a S4 method of some other package

问题描述

实际问题

如何避免Rd文件名冲突

1. 一个S4泛型及其方法而非必须全部在同一个包中定义（包含（某些）自定义方法的包依赖于包含泛型的包）和
使用 roxygenize（）从
2. 。 org / web / packages / roxygen2 / index.htmlrel =noreferrer> roxygen2 生成实际的Rd文件？
   

我不确定这是否是 roxygen2 问题，或者当泛型及其方法分散在不同包中时常见的问题（恕我直言，如果遵循模块化编程风格，则是一种现实的用例场景）。

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

包中 pkga

假设在 pkga 包中定义了一个泛型方法 foo ，并且提供了相应的roxygen代码 roxygenize（）选择生成Rd文件：

 ＃'测试函数
＃'
＃'测试功能。 
＃'
＃'@param ...更多参数。 
＃'@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 
 $ b $ setMethod（
f =foo ，
签名=签名（x =ANY），
定义= cmpfun（函数（
x，
 ... 
）{
 return（ TRUE）
}，options = list（suppressAll = TRUE））
）
  

然而，如果包 pkga 为 foo 提供了通用，并且您决定在其他包中（比如 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，字符方法
＃'@export 
 $ b $ setMethod（
f =foo （b $ bx，
 ... 
）{
 return（ x）
}，options = list（suppressAll = TRUE））
）
  

更确切地说，这是抛出/写入文件 00install.out

 错误：Q：/pkgb/man/foo-methods.Rd：Sections \title和\\\
ame必须存在并且在Rd文件中是唯一的
错误：安装Rd对象失败'pkgb'
  

到期美元

I尝试将 @rdname 和 @aliases 的值更改为 foo_pkgb * （而不是 foo * ），但是 \title 和 \ name 仍然设置为 foo ，因此roxygenizing和错误remai纳秒。任何想法除了手动编辑由 roxygenize（）？

生成的Rd文件

---

编辑2012年12月1日

鉴于开始赏金，实际的问题可能会略微宽泛些： p>

我们如何实现对Rd文件的某种内部包检查和/或我们如何合并分散在包中的S4方法帮助文件一个单一的Rd文件是为了给最终用户提供一个单一的参考来源？

解决方案

问题确实是roxygenize - 只有。
这就是为什么我从来没有看到过这个问题。

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

请求更少的极端roxygenation

由此产生的帮助页面往往看起来很无聊，不仅是自动生成的.Rd文件，而且还有渲染结果。
例如

1. 例子通常很少，不包含注释，通常格式不正确（使用空格，/新行/ ..）


2. 数学问题很少通过\eqn {}或\ deqn {}
解释，

3. \describe {..}和类似的高级格式化很少使用

为什么会这样？由于

<1>阅读和编辑roxygen评论比阅读和编辑更多
繁琐或至少在视觉上不吸引人的
* .Rd ESS或Rstudio中的文件或（其他IDE内置有* .Rd支持的）

2）如果您使用了该文档

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

你通常不会考虑写出完整的R文档作为重要的
（而是你的R代码，所有的文档只是 一个评论： - ）

所有这一切的结果：人们更喜欢在小插曲，甚至是博客，github gists，youtube视频或其他在创作时非常好的地方写文档，但是是
几乎与代码分离并且必然会过时和枯萎（因此，通过Google搜索误导你的useRs）
- >在同一个地方有代码和文档的roxygen的原始动机完全被打败。

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

Actual question

How do I avoid Rd file name conflicts when

1. a S4 generic and its method(s) are not necessarily all defined in the same package (package containing (some of) the custom method(s) depends on the package containing the generic) and
2. using roxygenize() from package roxygen2 to generate the actual Rd files?

I'm not sure if this is a roxygen2 problem or a common problem when the generic and its method(s) are scattered across packages (which IMHO in general definitely is a realistic use-case scenario if you follow a modular programming style).

What's the recommended way to handle these situations?

Illustration

In package pkga

Suppose in package pkga you defined a generic method foo and that you've provided the respective roxygen code that roxygenize() picks up to generate the Rd file:

#' 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")       
    }
)

When roxygenizing() your package, a file called foo-methods.Rd is created in the man subdirectory that serves as the reference Rd file for all methods that might be created for this generic method. So far so good. If all of the methods for this generic are also part of your package, everything's good. For example, this roxygen code would make sure that documentation is added to foo-methods.Rd for the ANY-method of 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))
)

However, if package pkga provides the generic for foo and you decide in some other package (say pkgb) to add a foo-method for x being of class character, then R CMD check will tell you that there is a name clash with respect to Rd file names and/or aliases (as there already exists a Rd file foo-methods.Rd in pkga):

In package 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))
)

To be more precise, this is the error that's thrown/written to file 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'

Due dilligence

I tried to change the values for @rdname and @aliases to foo_pkgb* (instead of foo*), but \title and \name still are set to foo when roxygenizing and thus the error remains. Any ideas besides manually editing the Rd files generated by roxygenize()?

---

EDIT 2012-12-01

In light of starting the bounty, the actual question might get a slightly broader flavor:

How can we implement some sort of an "inter-package" check with respect to Rd files and/or how can we consolidate S4 method help files scattered across packages into one single Rd file in order to present a single source of reference to the end-user?

解决方案

The basic question is indeed "roxygenize"-only. That's why I never had seen the problem.

While there are good reasons for the roxygenizing approach of package development, I still see a very good reason not to go there:

Plea for much less extreme roxygenation

The resulting help pages tend to look extremely boring, not only the auto generated *.Rd files but also the rendered result. E.g.

1. examples are often minimal, do not contain comments, are often not well formatted (using space, / new lines /..)
2. Mathematical issues are rarely explained via \eqn{} or \deqn{}
3. \describe{ .. } and similar higher level formatting is rarely used

Why is that? Because

1) reading and editing roxygen comments is so much more "cumbersome" or at least visually unrewarding than reading and editing *.Rd files in ESS or Rstudio or (other IDE that has *.Rd support built in)

2) If you are used that documentation

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

you typically tend to not considerung well written R documentation as something important (but rather your R code, to which all the docs is just a comment :-)

The result of all that: People prefer writing documentation about their functions in vignettes or even blogs, github gists, youtube videos, or ... where it is very nice at the time of authoring, but is pretty much detached from the code and bound to get outdated and withering (and hence, via Google search misleading your useRs) --> The original motivation of roxygen of having code and documentation in the same place is entirely defeated.

I like roxygen and use it extensively at the time I create a new function... and I keep and maintain it as long as my function is not in a package, or is not exported. Once I decide to export it, I run (the ESS equivalent of) roxygenize() once and from then on take the small extra burden of maintaining a *.Rd file that is well formatted, contains its own comments (for me as author), has many nice examples, has its own revision control (git / svn / ...) history, etc.

这篇关于扩展某个其他包的S4方法时，Rd文件名会发生冲突的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！