title: Rd file name conflict when extending a S4 method of some other package
body: <h2>Actual question</h2>
  
  <p>How do I avoid Rd file name conflicts when </p>
  
  <ol>
  <li>a S4 generic and its method(s) are <strong>not</strong> necessarily all defined in the same package (package containing (some of) the custom method(s) depends on the package containing the generic) <strong>and</strong></li>
  <li>using <code>roxygenize()</code> from package <a href="http://cran.r-project.org/web/packages/roxygen2/index.html" rel="noreferrer">roxygen2</a> to generate the actual Rd files?</li>
  </ol>
  
  <p>I'm not sure if this is a <code>roxygen2</code> 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). </p>
  
  <p><strong>What's the recommended way to handle these situations?</strong></p>
  
  <h2>Illustration</h2>
  
  <p><strong>In package <code>pkga</code></strong></p>
  
  <p>Suppose in package <code>pkga</code> you defined a generic method <code>foo</code> and that you've provided the respective roxygen code that <code>roxygenize()</code> picks up to generate the Rd file:</p>
  
  <pre><code>#' 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")       
      }
  )
  </code></pre>
  
  <p>When <code>roxygenizing()</code> your package, a file called <code>foo-methods.Rd</code> is created in the <code>man</code> 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 <code>foo-methods.Rd</code> for the <code>ANY</code>-method of <code>foo</code>:</p>
  
  <pre><code>#' @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))
  )
  </code></pre>
  
  <p>However, if package <code>pkga</code> provides the generic for <code>foo</code> and you decide in some other package (say <code>pkgb</code>) to add a <code>foo</code>-method for <code>x</code> being of class <code>character</code>, then <code>R CMD check</code> 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 <code>foo-methods.Rd</code> in <code>pkga</code>):</p>
  
  <p><strong>In package <code>pkgb</code></strong></p>
  
  <pre><code>#' @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))
  )
  </code></pre>
  
  <p>To be more precise, this is the error that's thrown/written to file <code>00install.out</code></p>
  
  <pre><code>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'
  </code></pre>
  
  <h2>Due dilligence</h2>
  
  <p>I tried to change the values for <code>@rdname</code> and <code>@aliases</code> to <code>foo_pkgb*</code> (instead of <code>foo*</code>), but <code>\title</code> and <code>\name</code> still are set to <code>foo</code> when roxygenizing and thus the error remains. Any ideas <strong>besides manually editing the Rd files</strong> generated by <code>roxygenize()</code>?</p>
  
  <hr>
  
  <h2>EDIT 2012-12-01</h2>
  
  <p>In light of starting the bounty, the actual question might get a slightly broader flavor: </p>
  
  <p><strong>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?</strong></p>