Re: generating a manual from annotations in source code

[Mikael Djurfeldt <mdj@nada.kth.se>]

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?

If this is the case, then there might be alternative solutions to
*that* problem.  E.g., if the programmer is adding a new function, it
is possible to write an Emacs function which looks up the definitions
of the neighboring functions in the texinfo code, splits the window,
and positions the cursor at a putative place in the texinfo
file---something in the style of C-x 4 a.

Also, note that while it is difficult to automatically generate a
well-structured manual, it may be easier to try to write texinfo
function descriptions as self-contained as possible so that we could
have a function in (ice-9 session):

  (info <procedure>)

which looks up and prints the info entry of the procedure.

I.e., it might be possible to go the other way, using the info
documentation also as docstrings...

/mdj