Re: generating a manual from annotations in source code

[thi <ttn@netcom.com>]

Jim Blandy <jimb@red-bean.com> writes:

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

sort of but not entirely.  definitely docstring-grokking support
reduces the inconvenience barrier to a point where it is indeed
natural to throw a few words in the source.  but i don't see it as a
either-or situation; having a separate file encourages conceptual and
task-oriented (ugh) documentation.

i prefer access to both approaches w/ docstring-grepping relegated to
a reference or internals manual.  other programmers i know simply
avoid documentation, claiming the required skillset makes all efforts
by the non-skilled ineffective and actually dangerous (eg, out-of-sync
docs causing catastrophic operator error).  obviously there are many
views.

thi