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

Wag

Answer 1

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.

Dionne

thanks a lot for answering, martin! I totally see your point. However, I disagree with several aspects of your argumentation (I'll explain them in more detail next week). I'd be more than happy to discuss this with you! – Wag

Answer 2

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.

Breen