Re: [S] RE: Documentation

Scott.Chasalow@USERS.PV.WAU.NL
Thu, 28 May 1998 10:20:40 -0200


On Wed May 27 23:22:09 1998,
Bob Dorazio <Bob_Dorazio@usgs.gov> wrote:
> We can anticipate some enhancements in documentation when version 4 of the
> S language is implemented in S-PLUS. According to John Chambers
> ("Evolution of the S language",
> http://cm.bell-labs.com/cm/ms/departments/sia/project/S/index.html), in
> version 4 of the language on-line help will be driven entirely from S
> objects, rather than from text files. Chambers writes
>
> "If the user requests documentation for a function and no explicit
> documentation exists, S will now construct documentation of the function
> call and argument defaults from the function itself. If there are initial
> comments in the function definition, these will be used as a description
> of the function. Provided programmers just remember to add a few lines of
> comments, functions can be usefully documented from their first writing."

In reply to the skeptics, I expect this development fortuitously to mesh very
well with my long-standing mode of operation when writing S-PLUS functions.
For any function except the most trivial or temporary, I write the help file
as
initial lines of comments in the function body as I'm writing the function.
Sometimes this is only a partial help file, sometimes it is complete, but it
always gives at a minimum the DESCRIPTION and ARGUMENTS
sections (the USAGE section comes gratis). I have even written a function,
head(), to extract out of a function only these initial comment lines. Sounds
as if this functionality, or something quite like it, will be merged into
help() in S4.

(Warning, Sermon Alert: The Value to the Programmer of Good and Timely
Documention. (I agree with Duncan Murdoch and Anthony Rossini. But then
who wouldn't?) This practice has the obvious advantage of forcing me to
get at least the core of the documentation down in writing before my memory
is wiped of all clues to what the function is supposed to be doing and how it
works. As an added bonus, I find it also helps me to spot more quickly
potential bugs or omissions, and to crystallize my ideas for the design of
the function. Sure it costs more time in the short run, but in the long run,
when
I have had to return to a function years (or even a week) later, it has saved
far more time, and allowed me to re-use or modify old functions that
otherwise probably would have been close to useless.)

Returning to the point, I'm not claiming there is a particular advantage to
including the help text in the function body instead of in a separate file
(although there certainly should be SOME comments in the function body);
only that some of us who have done so should, I expect, indeed find this S4
development a very useful enhancement. I do not see how this development
could be "several steps back" (to quote Brian Ripley), even for release code.
I agree it may be no steps forward for some currently inadequately
documented functions, but how can it hurt? Perhaps if it were to encourage
programmers in the future to neglect to produce proper help files? I hope
not too big a risk...

For important functions, or those intended for wider consumption, I always
INTEND to move the help text out of the function body and into a proper
help file. Somehow or other I don't always manage to get to it. So much
for good intentions. A smarter system would be to automatically open an
editor on both a function body and a corresponding separate help file
simultaneously, with a single command (or function call) (as suggested
in Anthony Rossini's comments). I used to have a rudimentary version
of such a system in S-PLUS, but it fell into disuse and disrepair.
I suppose I must have found working with only one file more convenient.
Maybe its time to try again...

Cheers,
Scott
=========================================
Scott.Chasalow@users.pv.wau.nl

Wageningen Agricultural University
Laboratory of Plant Breeding
P.O. Box 386
6700 AJ Wageningen
THE NETHERLANDS

http://www.spg.wau.nl/pv/staff/Chasal_S.htm
===========================================
-----------------------------------------------------------------------
This message was distributed by s-news@wubios.wustl.edu. To unsubscribe
send e-mail to s-news-request@wubios.wustl.edu with the BODY of the
message: unsubscribe s-news