maechler at stat.math.ethz.ch
Tue Dec 27 12:48:54 CET 2011
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 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
More information about the ESS-help