Re: [S] RE: Documentation

Paul Gilbert (pgilbert@bank-banque-canada.ca)
Thu, 28 May 1998 11:11:57 -0400


Scott Chaslow wrote:
>I write the help file as initial lines of comments in the function body
...
>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.
...
>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

For nearly four years now I have been writing HTML style comments between /* */
as a header in the same files as my code. I run this through a simple awk filter
which separates the help from the code. A modified version of source I call
hsource makes this very workable. The choice of HTML was because I wanted one
set of documentation that worked for both Windows and Unix, and the power of
browsers and search engines for looking at it. I'm not sure S4 will be an
improvement, but that is a separate discussion.

I do find that including the help in the code file is a very useful practice.
Before converting to this system I tried to maintain help in a separate file,
but it was often very inconvenient to go and find the location of documentation
and modify it while I was developing code. I found that I had two problem:

1/ Comments in the code did not agree with the documentation I was keeping in a
separate file.
2/ The documention was often out-of-date, incorrect, or incomplete.

By removing the comments and placing the information in the help documentation
which was conveniently there in the code file I eliminated the former.

What I would really like is some automatic way to check if the help is correct.
In theory it should be possible to do some things like

-check if documention arguments match function arguments (trivial of course if
help is generated from the function, but not so otherwise).

-check that arguments are all documented.

-check that results usually correspond to documented results.

-check that examples work.

-check that "see also" references actually exist.

-check if the system is user friendly enough that documentation can be
eliminated.

Paul Gilbert

-----------------------------------------------------------------------
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