[Roxygen-devel] Roxygen2 3.0.0

[Carl Boettiger]

Hi Hadley,

That's great news!

Um, I'm still unclear on what information I do need to properly document
the S4 methods.  Without adding any roxygen documentation, check is
unhappy, e.g.

    Undocumented S4 methods:
      generic 'c' and siglist 'codeDefinition'

What should I be doing here?



On Tue, Jan 21, 2014 at 4:54 AM, Hadley Wickham <h.wickham at gmail.com> wrote:

> Hi Carl,
>
> That advice is totally out of date. You shouldn't need to do anything
> special for S4 methods.
>
> Hadley
>
> On Mon, Jan 20, 2014 at 11:03 PM, Carl Boettiger <cboettig at gmail.com>
> wrote:
> > 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/
>
>
>
> --
> http://had.co.nz/
>



-- 
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/20140121/402f1876/attachment.html>