title: How to properly document S4 methods using roxygen2
body: <p>I've seen some discussions in SO and other places regarding how this should be or will be done in future versions of Roxygen2. However, I am stuck. How should I go about documenting a S4 generic, as well as its methods, using Roxygen2? A working example for a brand new generic/methods, as well as an example for extending base S4 generic would be incredibly useful. I do not want to have to make separate (mostly) redundant documentation for each S4 method of the same generic. </p>
  
  <p>Due dilligence:
  I have tracked down a useful example for the "extract" method. However, it appears to be outdated and incomplete for my question. It uses @slot tag in the class documentation, which is not (no longer?) supported. It only shows an extension of a core S4 method "[", rather than a complete Roxygen example including the documentation of the S4 generic. </p>
  
  <p><a href="https://stackoverflow.com/questions/4396768/how-to-properly-document-s4-and-methods-using-roxygen">How to properly document S4 &quot;[&quot; and “[&lt;-“ methods using roxygen?</a></p>
  
  <p>If I fully document a new S4 generic with title, description <code>@param @return @name @aliases 
  @docType @rdname</code>, and then document the S4 method with just the corresponding <code>@name @aliases 
  @docType @rdname</code>, I get the following <code>R CMD check</code> warning:</p>
  
  <pre><code>* checking for missing documentation entries ... WARNING
  Undocumented S4 methods:
  &lt;&lt; long list of apparently undocumented methods. E.g. generic 'plot' and siglist 'myClass1,ANY' &gt;&gt;
  All user-level objects in a package (including S4 classes and methods)
  should have documentation entries.
  </code></pre>
  
  <p>It looked at first as though none of my S4 methods documented in this fashion with roxygen2 had actually worked. However, so far, I've noticed that my extensions of the core method "show" do not have an associated error, even though they were documented in exactly the same way as the rest. Here is an example of the complete roxygen documentation I included above one of the show methods, that did NOT generate the missing-documentation error:</p>
  
  <pre><code>#' @name show
  #' @aliases show,myClass2-method
  #' @docType methods
  #' @rdname show-methods
  </code></pre>
  
  <p>Thus, I'm at a loss. As you can see, I've included the convention for aliases for S4 methods described in <a href="http://cran.r-project.org/doc/manuals/R-exts.html#Documenting-S4-classes-and-methods" rel="noreferrer">the S4 documentation section of the R package manual</a>, namely that methods should have an alias with the following name (without space):</p>
  
  <pre><code>generic,signature_list-method.
  </code></pre>
  
  <p>Somehow, this is not completely being understood by <code>R CMD check</code>.</p>
  
  <p>Finally, after building the documentation using: </p>
  
  <pre><code>library("devtools")
  library("roxygen2")
  document("mypkgname")
  check_doc("mypkgname")
  </code></pre>
  
  <p>and building the package, I get functioning documentation. Any titles from a specific method's documentation winds up in the 'Description' field, rather awkwardly. So roxygen2 obviously did something with each method's documentation and is on the right track. However, it is not enough to avoid a large and troubling warning from </p>
  
  <pre><code>&gt; R CMD check mypkgname
  </code></pre>
  
  <p>I've looked at the Rd files, but I know even less about them to quickly see what's the problem is, and I anyway want to know the roxygen2 solution so that I will not have to manipulate the Rd files directly after each documentation revision.</p>
  
  <p>So this is a multipart question:</p>
  
  <ol>
  <li><p>What is the current recommended approach for both S4 generic and S4 method documentation with roxygen2?</p></li>
  <li><p>Is there a good example available somewhere that shows the complete details?</p></li>
  <li><p>What might be the cause, and solution, to the  warning that documentation for most S4 methods is missing (even though the methods with "missing" documentation actually have had their doc parsed by roxygen2 and the resulting Rd files are at least good enough to work in the package after <code>R CMD build mypkgname</code>) ?</p></li>
  </ol>