[Roxygen-devel] Roxygen2 3.0.0

[Hadley Wickham]

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/