[R] Roxygen vs Sweave for S4 documentation

[Martin Maechler]

>>>>> "DM" == Duncan Murdoch <murdoch at stats.uwo.ca>
>>>>>     on Mon, 22 Jun 2009 09:41:12 -0400 writes:

    DM> On 6/22/2009 9:23 AM, Tobias Verbeke wrote:
    >> On Mon, Jun 22, 2009 at 2:18 PM, Douglas Bates<bates at stat.wisc.edu> wrote:
    >>> On Mon, Jun 22, 2009 at 7:12 AM, Martin
    >>> Maechler<maechler at stat.math.ethz.ch> wrote:
    >>>>>>>>> "TobiasV" == Tobias Verbeke <tobias.verbeke at openanalytics.be>
    >>>>>>>>> on Sun, 21 Jun 2009 08:25:07 +0200 writes:
    >>>> 
    TobiasV> Hi Ken,
    >>>> >> I have been using R for a while.  Recently, I have begun converting my
    >>>> >> package into S4 classes.  I was previously using Rdoc for documentation.
    >>>> >> Now, I am looking to use the best tool for S4 documentation.  It seems that
    >>>> >> the best choices for me are Roxygen and Sweave (I am fine with tex).
    >>>> >>
    >>>> >> Are there any users of Roxygen or Sweave who can comment on the strengths or
    >>>> >> weaknesses of one or othe other?  Thanks in advance.
    >>>> 
    TobiasV> For the moment proper documentation of S4 classes (with a @slot tag
    TobiasV> e.g.) is not implemented yet,
    >>>> 
    >>>> how did you define "proper" here?
    >>>> 
    >>>> I know that the result of  promptClass()  may not always be
    >>>> perfect. As most things are not perfect,
    >>>> I would not quickly call this improper ...
    >>>> 
    >>>> Or is using *.Rd  not proper for you,
    >>>> as it does not have all of code + docs in one file?
    >>> 
    >>> I think Tobias was referring to Roxygen support for S4 classes, not
    >>> the existence of .Rd tags.
    >> 
    >> Yes, I was just referring to the Roxygen support and as a matter of
    >> fact I recommended Roxygen to mimick the nice job done by promptClass
    >> a while ago
    >> 
    >> https://lists.r-forge.r-project.org/pipermail/roxygen-devel/2009-February/000023.html
    >> 
    >> No intent to criticize nor current Rd tags nor Rd as a documentation system,
    >> although having code + docs in one file (as in Roxygen) seems to be convenient
    >> to some.

    DM> Hopefully the Rd changes coming in R 2.10.0 will enhance either way of 
    DM> generating an Rd file.  There are some things (e.g. all the methods for 
    DM> a generic, or all the generics with methods for a class, all the classes 
    DM> extending a given one) that aren't known at the time you run promptClass 
    DM> or Roxygen, but which are known at display time; the new system should 
    DM> allow those to be computed just before displaying the page.

Yes, indeed!
S4 classes and methods are indeed a very good example why a
dynamic help system as you are envisaging is very desirable.
Thanks a lot, Duncan, for your work on this!

Martin