R devel - Dec 2012 - Workarounds/solutions to Rd file name conflict when extending a S4 method of some other package

Dear list,

this is a re-post of my post to r-help on 2012-30-11. Duncan Murdoch did 
provide a great pointer to a possible workaround, but I'm still eager to 
check out other ways. So I hope it's okay to get this out on r-devel now 
as well:

// IN SHORT //
What are possible workarounds to "consolidate" documentation for S4 
methods that are scattered across different packages (generic and some 
custom methods in one package, additional custom methods in another 
package) in a *single* Rd help file while using package 'roxygen2' to 
generate the actual Rd files?

// ADDITIONAL INFORMATION //
First of, here are the three facts that "cause" my problem:

1) I'd like the software, i.e. the packages, that I write to be as 
extendable as possible
2) I pretty much ended up using S4 functionality in everything I do
3) I'm a big fan of "in-file documentation" and package
'roxygen2' does
a wonderful job in helping me out keeping my Rd help files synced

That being said, it is a quite common scenario that some package (say 
'pkga') contains the *generic* method/function 'foo()' as well
as *some*
custom methods (for different data types of the available signature 
arguments).

Now, let's suppose that someone using 'pkga' and building a new
package
(say 'pkgb') would like to build upon the generic method
'pkga::foo()'
and provide some more custom methods for it. When he sticks to the 
suggested workflow (especially with respect to the way the roxygen2 code 
is written), then R CMD check will rightly(!) complain that an Rd file 
with the respective name (generated by 'roxygenize()') already exists 
(because it is already part of 'pkga').

My question is hence twofold:
1) What would be possible workarounds that allow me to a) keep using 
'roxygen2' and link documentation of pkga::foo() with that of 
pkgb::foo() (as they do belong together conecptionally)
2) Is there a need to address this problem on a higher level in the 
future? My feeling is that more people are starting to use S4 which, 
IMHO, is a good thing as it allows to systematically build upon code of 
other programmers. But then I guess we would need some sort of an 
"inter-package" check and/or help-file consolidation to present the
user
a single source of documentation for some S4 method.

I tried to illustrate the problem with actual code in this post at 
Stackoverflow: 
http://stackoverflow.com/questions/13137912/rd-file-name-conflict-when-s4-generic-and-methods-are-not-in-the-same-package


Best regards,
Janko



	[[alternative HTML version deleted]]