[ESS] Roxygen

[Martin Maechler]

I have been asked in a private e-mail

> I notice that in much of your R code there are commented Roxygen tags. I
> thus assumed you used Roxygen in the past but gave it up. If this is the
> case, I am curious- would you not recommend it's usage?

and answered the following ... which I now think I should "blog
to ESS-help"

To the contrary; I continue using it.... however:

I see two principal ways of using Roxygen ... or rather, two corners
of a continuum of using Roxygen:

1)  Roxygen as *the* way to put almost all documentation for an R
    function, notably its full help page as part of the R code,   
    and then -- when that is part of an R package -- 
    autogenerate the man/*.Rd help pages via Roxygen

2) Roxygen for producing an outline of a documentation;
    a) for functions that are not (yet) part of a package
    b) for functions that are not exported from a package
    c) when writing a new function, *before* writing the *.Rd file,
       write things in Roxygen and later *generate* the *.Rd page from that

My own use of Roxygen is clearly  '2)' : In ESS (which I use all the
time), there is so much convenient support
for editing *.Rd files, which I really want to use.  Also *.Rd files
from the point of view of R are ``objects'' themselves in sofar as
they are parsed, example-extracted, etc etc
Also, *.Rd files are not 1:1 with R objects, but often conveniently
document several R objects (functions, classes, methods, ...) at once.
In my view, the Roxygen concept attaches documentation 1:1 to an R
object, or at least to R objects defined closely
together.... which is a bit less flexible.

"Just my 2 cents".

Martin Maechler, ETH Zurich