[Rd] Flat documentation?
Wed Dec 11 21:25:03 2002
Dear Paul, Duncan, et al.,
I too like the package-construction tools in R, and find it easier to
assemble R packages than S-PLUS libraries.
I wonder, however, whether the following simple suggestion might prove
useful: Suppose that help(foo) and ?foo first look for standard
documentation. If such documentation exists, it would be processed as at
present. If there is no standard documentation on foo, then help and ?
would look for a "doc" attribute of foo (or for initial comment lines in
the function definition, if foo is a function), and, if this exists,
display the contents in a pager.
At 10:17 AM 12/11/2002 -0500, Paul Gilbert wrote:
>I am a bit concerned about the direction of some of this discussion.
>do not consider gutting the R package Quality Assurance system and start a
>back to the chaos of Statlib. There has to be a mechanism that weeds out code
>that no longer works or is inadequately documented. Do you realize how
>people have wasted trying to make poorly documented "casual" Statlib code
>There is nothing that prevents non CRAN distribution of code and casual
>documentation. Posting of an r-help message with a web site link does make
>fairly easily accessible to anyone who searches the help archives, and
>no need for the code or documentation to be in any special format. CRAN
>a devel area for packages that are not yet in good enough shape for the
> >In fact, one of my colleagues has chosen to use S-PLUS instead of R
> >partly because it's easier to document the stuff he's written.
>I have mostly gone the other way, largely because of the QA tools (which in
>large part are possible because of the Rd format). It is worth pointing out to
>your colleagues that there is short term pain for long term gain. The fact
>code and documentation arguments are matched, and examples are checked, means
>that documentation does not need to be manually checked all the time as your
>code evolves. Changes that require changes in the documentation tend to be
>pointed out automatically.
Department of Sociology