[Roxygen-devel] [roxygen2] roxygenise, setGeneric and .svn directory

[Manuel J. A. Eugster]

On 8/15/11 11:58 PM, Brian G. Peterson wrote:
> On Mon, 2011-08-15 at 15:32 -0500, Yihui Xie wrote:
>> I don't remember there was a tag named @rdfile; at least in roxygen2
>> it is @rdname.
>
>
> My mistake, sorry.  roxygen2 is brand new to most of us.
>
>> I guess @rdname is not very often used, so a little bit manual
>> tweaking to the auto-generated roxygen comments should not be too
>> hard.
>
> That would be an incorrect guess, at least for my packages, where
> several similar functions share a function signature, and can therefore
> share a lot of documentation.
>
> In roxygen, I had to go through and delete a bunch of 'empty' Rd files
> generated every time, despite @alias commands that signaled which other
> functions were documented by that documentation block.

Just for the sake of completeness: @rdname is/was also available in
roxygen and in combination with @nord (which disables the creation of
an Rd file) you should be able to to do it without doing something by
hand!


>> Anyway, I will be glad to include support for @rdname in
>> Rd2roxygen when I'm free.
>
> Thank you.
>
>
>> BTW, as Hadley said, it is painful to maintain documentation partly by
>> Rd and partly by roxygen. I really wonder this rationale.
>
> Part of it is conversion on older packages.  Rd2roxygen has not
> completely worked for me ever, though I did use it in a conversion on a
> newer package when Rd2roxygen was released, and then maintained that in
> roxygen.  Part of it is that I typically write the -package.Rd file by
> hand, because there is no obvious way to do that in roxygen
> (documentation references appreciated).  Another part is for data sets,
> examples, etc, which again are not completely obvious in their method of
> documenting using roxygen.

Yeah, that's how you should use it: write static documentation, e.g.,
data set documentation by hand; and generate "more dynamic" 
documentation like source code documentation using roxygen.


Manuel.