On Wed, 27 May 1998, Bob Dorazio wrote:
> All:
>
> 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."
>
> I think the last sentence speaks volumes. Most programmers, especially
> myself, could do a better job of documenting their code. I have no
> experience with version 4 of S, but I am curious to see whether
> self-documentation, as implemented and practiced, really is an
> enhancement.
That last sentence is the critical one. Self-documentation as currently
exists seems to me to be several steps back for release code. Nothing
whatsoever will get options such as axs in a scales list in a Trellis plot
buried in (I'm told 500 lines of) code documented except if the designer
does so. For most useful S objects, explicit documentation must exist,
and nothing in the quote (nor the practice) implies that is in S objects.
I sympathize with earlier comments about reading the S code of
render.trellis (although search facilities help). The great thing about
S-PLUS is that at least some of us _can_ read the S code, and that is how
a lot of things have become known. In contrast, the GUI absolutely needs
documentation, as there is very little which can be investigated.
--
Brian D. Ripley, ripley@stats.ox.ac.uk
Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
University of Oxford, Tel: +44 1865 272861 (self)
1 South Parks Road, +44 1865 272860 (secr)
Oxford OX1 3TG, UK Fax: +44 1865 272595
-----------------------------------------------------------------------
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
|