Rd file name conflict when extending a S4 method of some other package

Question

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 sa

Answer 1

I managed to generate NAMESPACE and *.Rd files for S4 methods for generics defined in another package than mine.

It took me the following steps:

1. Create NAMESPACE by hand as a workaround to a known roxygen2 bug.

   Writing a NAMESPACE by hand is not so difficult at all!

   Switch off NAMESPACE generation by roxygen2 in RStudio:

   Build > more > Configure build tools > configure roxygen > do not use roxygen2 to generate NAMESPACE.
   

2. import the package containing the generic and export the S4 methods using exportMethods.

3. Write separate roxygen2 documentation for each of the S4 methods. Do not combine roxygen2 documentation (as I generally do for different methods of the same generic).

4. Add explicit roxygen tags @title and @description to the roxygen documentation of the S4 methods. Write @description explicitly, even if its value is identical as @title.

That makes it work for me.

Answer 2

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.