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

[Yihui Xie]

OK I see. To be clear, Rd2roxygen certainly cannot guarantee a perfect
transition from Rd to roxygen. Depending on the complexity of the
documentation files, it often requires some manual input or
modifications on the output, especially in the case that several
functions share the same Rd file. My experience is that it will pay
off after one or two hours' work on the transition.

As far as I know, roxygen2 will not generate empty Rd files (yes, the
old roxygen package did).

Regards,
Yihui
--
Yihui Xie <xieyihui at gmail.com>
Phone: 515-294-2465 Web: http://yihui.name
Department of Statistics, Iowa State University
2215 Snedecor Hall, Ames, IA



On Mon, Aug 15, 2011 at 4:58 PM, Brian G. Peterson <brian at braverock.com> 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.
>
>
>> 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.
>
> I do now run roxygen2 in place, as I said, since the @rdname tag
> eliminates most of my problems.  svn diff takes care of the rest.
>
> Regards,
>
>   - Brian
>
>
>