[R] Workarounds to Rd file name conflict when extending a S4 method of some other package

[Duncan Murdoch]

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