Rd file name conflict when extending a S4 method of some other package
generics, package, r, r-s4, roxygen2
Solution
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.
- examples are often minimal, do not contain comments, are often not well formatted (using space, / new lines /..)
- Mathematical issues are rarely explained via \eqn{} or \deqn{}
- \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.
Problem
Actual question How do I avoid Rd file name conflicts when - 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 - 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?