[Roxygen-devel] Roxygen2 3.0.0

[Carl Boettiger]

Hi roxygen-list,

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](
http://stackoverflow.com/questions/7356120/how-to-properly-document-s4-methods-using-roxygen2)
(Happy to get any pointers to other tutorials on the S4 roxygen too).  I'm
currently stuck trying to document a "concatenate" method:

The method looks like this: (See the [full package](
https://github.com/ropensci/EML/tree/7d0f006cdcae2f89e667b2c4163083da52e6e147
))

    #' @rdname c-methods
    #' @aliases c,attribute,ANY-method
    setMethod("c", signature("attribute"), function(x, ...)
new("ListOfattribute", list(x, ...)))

With which `devtools::document(".")` works just fine, but then `check(".")`
complains:

    Error : /tmp/Rtmpu87hGh/Rbuild785f32a6d07b/EML/man/c-methods.Rd:
Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'EML'


Not sure why check should fail when document works, or what fields I need
to add.


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?


Thanks for any hints or suggestions.

Cheers,

Carl


On Fri, Nov 15, 2013 at 5:57 AM, Hadley Wickham <h.wickham at gmail.com> wrote:

> Hi all,
>
> This is just a quick note to let you know that I'm moving towards a
> new release of roxygen2, bringing in the most important new features
> and bug fixes from roxygen3. The most important new features are:
>
> * S4 support (generics, methods and classes), generating correct
> aliases and usage statements
>
> * Better S3 support, so that you can just do `@export`, not
> `@S3method` or `@export` + `@method` depending on whether you're
> documenting the function or just exporting the definition
>
> * I've also fixed a number of bugs to do with namespaces, usages and
> escaping, so generally the set of situations where you need to
> manually specify usage should be much much smaller.
>
> * I'm moving towards a system where you can turn off wrapping
> (https://github.com/klutometis/roxygen/pull/142) - this will be opt-in
> in the current version of roxygen, but will eventually become the
> default. It's just too hard to get wrapping right automatically, and
> it causes a lot of problems for new users.
>
> You can see a complete list of changes at
> https://github.com/klutometis/roxygen/blob/master/NEWS.
>
> If you are using roxygen for S4 currently, I'd really appreciate it if
> you'd try it out - you should now be able to remove any custom @alias
> and @usage tags.  You can try out the dev version with:
>
> install.packages("devtools")
> devtools::install_github("devtools")
> devtools::install_github("roxygen", "klutometis")
>
> You'll also need a development environment since roxygen2 now includes
> a little C++ code for better escaping (and will probably include more
> over time as identify performance benchmarks and move them to C++).
>
> If you discover any bugs, please file at
> https://github.com/klutometis/roxygen/issues. I'll also consider small
> new features, but while roxygen2 is now in much better shape than it
> was a couple of weeks ago, it's still not easy to add new features.
>
> Hadley
>
> --
> Chief Scientist, RStudio
> http://had.co.nz/
> _______________________________________________
> Roxygen-devel mailing list
> Roxygen-devel at lists.r-forge.r-project.org
> https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel
>



-- 
Carl Boettiger
UC Santa Cruz
http://carlboettiger.info/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.r-forge.r-project.org/pipermail/roxygen-devel/attachments/20140120/e4d920e2/attachment.html>