generating a manual from annotations in source code

[Jim Blandy <jimb@red-bean.com>]

If you showed me a reference manual, and I looked it over and said it
looked like a good manual, and then you showed me that the manual was
generated automatically by extracting bits of text from source code,
then I wouldn't suddenly change my mind and call it a bad manual.  In
other words, if your doc extraction system tends to all the usual
details required for writing a good manual, then I'm sure you'll get a
good manual.  And I believe it is mechanically possible to do this.

My concern is that it will be unmaintainable, realistically, given the
human nature of maintainers.  If the layout of the code has any
influence on the layout of the manual, then you will sometimes find
places where good coding style conflicts with good manual style.
Certainly one can find compromises, but remember that these
compromises are only necessary at all because you're trying to extract
a manual from code.  If you just simply move the text out of the code
into the manual, then these tensions never exist in the first place.

Or, because the form of the manual is obscured by being scattered
throughout the source files, you will make changes that hurt the
manual without realizing it at all.

Did you ever read over the Java class documentation in the early days
of Java?  They had it on the web.  It was terrible.  You couldn't
figure anything out.  That's one example I have of a manual extracted
from docstrings.  I also know that Stallman was quite opposed to the
idea, and over the years I decided he was probably right.

It's just a gut feeling.  If you don't agree, you don't agree, and
you should go with your own gut feeling.


If the goal is to provide on-line documentation associated with SCWM
procedures, I would be much happier with a system that extracted in
the reverse direction: from a manual to a database accessible by the
code.

For example, go ahead and write texinfo or DocBook describing the SCWM
functions, then have a program grunge through the @deffn's (or the
DocBook equivalent) and build a database, then have SCWM retrieve
that text upon user request.

Or, if you think it is valuable to have the text mingled with the
source code, add a notation to your manual format that says "extract
the docstring for this function from the source, and insert it here."
That way, the layout of the source has no influence on the layout of
the manual.


Do people feel that, if the documentation is a separate file,
programmers will be discouraged from writing docs, whereas, if the
documentation were mingled with the source, then programmers would
naturally write docstrings as they go along?