Re: generating a manual from annotations in source code

[Nathan Froyd <maestrox@geocities.com>]

Jim Blandy wrote:
> 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?

Programmers are probably more inclined to write documentation directly
into the source code - the massive amounts of elisp code generated over
the years can attest to that.

Even seen the documentation distributed with Qt? It is automagically
generated from the source code, using conventions similar to javadoc's
/**...*/ pairs. While technically the only part of the documentation
that is written that way are the function references and class
references (Qt is written in C++), it is still very helpful stuff.

A properly written manual would probably be more generally useful, but
automagically generated documentation is a definite step in the right
direction.

Nathan