<div dir="ltr">Hi roxygen-list,<div><br></div><div>I'm having difficulty implementing S4 roxygen documentation.  I have no idea what the correct way to go about this is, so I am mostly extrapolating from this [stackoverflow answer](<a href="http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2">http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2</a>) (Happy to get any pointers to other tutorials on the S4 roxygen too).  I'm currently stuck trying to document a "concatenate" method: </div>
<div><br></div><div>The method looks like this: (See the [full package](<a href="https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147">https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147</a>))</div>
<div><br></div><div>    #' @rdname c-methods</div><div>    #' @aliases c,attribute,ANY-method</div><div>    setMethod("c", signature("attribute"), function(x, ...) new("ListOfattribute", list(x, ...)))</div>
<div><br></div><div>With which `devtools::document(".")` works just fine, but then `check(".")` complains: </div><div><br></div><div><div>    Error : /tmp/Rtmpu87hGh/Rbuild785f32a6d07b/EML/man/c-methods.Rd: Sections \title, and \name must exist and be unique in Rd files</div>
<div>ERROR: installing Rd objects failed for package 'EML'</div></div><div><br></div><div><br></div><div>Not sure why check should fail when document works, or what fields I need to add.  </div><div><br></div><div>
<br></div><div>As a side note, I find the roxygen documentation in the example above to be uninformative to a human (i.e. not really in the spirit of literate documentation), and rather tedious to enter when I have dozens of such concatenate methods, etc.  Without appreciating the details, it seems to me that ideally some of this could be generated programmatically from the method definition instead?</div>
<div><br></div><div><br></div><div>Thanks for any hints or suggestions.  </div><div><br></div><div>Cheers,</div><div><br></div><div>Carl</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham <span dir="ltr"><<a href="mailto:h.wickham@gmail.com" target="_blank">h.wickham@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi all,<br>
<br>
This is just a quick note to let you know that I'm moving towards a<br>
new release of roxygen2, bringing in the most important new features<br>
and bug fixes from roxygen3. The most important new features are:<br>
<br>
* S4 support (generics, methods and classes), generating correct<br>
aliases and usage statements<br>
<br>
* Better S3 support, so that you can just do `@export`, not<br>
`@S3method` or `@export` + `@method` depending on whether you're<br>
documenting the function or just exporting the definition<br>
<br>
* I've also fixed a number of bugs to do with namespaces, usages and<br>
escaping, so generally the set of situations where you need to<br>
manually specify usage should be much much smaller.<br>
<br>
* I'm moving towards a system where you can turn off wrapping<br>
(<a href="https://github.com/klutometis/roxygen/pull/142" target="_blank">https://github.com/klutometis/roxygen/pull/142</a>) - this will be opt-in<br>
in the current version of roxygen, but will eventually become the<br>
default. It's just too hard to get wrapping right automatically, and<br>
it causes a lot of problems for new users.<br>
<br>
You can see a complete list of changes at<br>
<a href="https://github.com/klutometis/roxygen/blob/master/NEWS" target="_blank">https://github.com/klutometis/roxygen/blob/master/NEWS</a>.<br>
<br>
If you are using roxygen for S4 currently, I'd really appreciate it if<br>
you'd try it out - you should now be able to remove any custom @alias<br>
and @usage tags.  You can try out the dev version with:<br>
<br>
install.packages("devtools")<br>
devtools::install_github("devtools")<br>
devtools::install_github("roxygen", "klutometis")<br>
<br>
You'll also need a development environment since roxygen2 now includes<br>
a little C++ code for better escaping (and will probably include more<br>
over time as identify performance benchmarks and move them to C++).<br>
<br>
If you discover any bugs, please file at<br>
<a href="https://github.com/klutometis/roxygen/issues" target="_blank">https://github.com/klutometis/roxygen/issues</a>. I'll also consider small<br>
new features, but while roxygen2 is now in much better shape than it<br>
was a couple of weeks ago, it's still not easy to add new features.<br>
<span class="HOEnZb"><font color="#888888"><br>
Hadley<br>
<br>
--<br>
Chief Scientist, RStudio<br>
<a href="http://had.co.nz/" target="_blank">http://had.co.nz/</a><br>
_______________________________________________<br>
Roxygen-devel mailing list<br>
<a href="mailto:Roxygen-devel@lists.r-forge.r-project.org">Roxygen-devel@lists.r-forge.r-project.org</a><br>
<a href="https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel" target="_blank">https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Carl Boettiger<br>UC Santa Cruz<br><a href="http://carlboettiger.info/" target="_blank">http://carlboettiger.info/</a><br></div>
</div>