R help - Nov 2012 - Workarounds to Rd file name conflict when extending a S4 method of some other package

Dear list,

// 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

On 12-11-30 5:38 PM, Janko Thyson wrote:
> Dear list,
>
> // 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?
I know nothing about roxygen2.  However, the .Rd format does allow for 
computation of results, so you could produce a .Rd file that at display 
time works out all the relevant links and displays them to the users.
There's very little use of this currently, so you may have to write 
support functions yourself, but if you do, and they work well, I'd be 
interested in bringing them into R for others to use.

Duncan Murdoch
>
> // 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
>
> ______________________________________________
> R-help at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide
http://www.R-project.org/posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>