Re: generating a manual from annotations in source code

[Tel <telford@eng.uts.edu.au>]

>     Jim> Or, if you think it is valuable to have the text mingled with
>     Jim> the source code, add a notation to your manual format that
>     Jim> says "extract the docstring for this function from the
>     Jim> source, and insert it here."  That way, the layout of the
>     Jim> source has no influence on the layout of the manual.
> 
>  This is like the dream I had...  Where `info' does that in GTK XEmacs
>  2000 beta 666, making it possible to write a good manual without having
>  to paste in those darn docstring snippets.  Let the viewing tool do
>  it for you.

Maybe a skeletal manual that includes introduction, tutorials and whatever
doesn't really have any relation to the code, then includes markers for
where to insert the extracted pieces that are directly related to the
code. With some care, the extraction process could leave footprints such that
the final result (info or html) includes links back into the code from
the manual. Then as you read the manual you can decide to edit some code
and jump straight to the definition of the function that you are reading about.

>     Jim> Do people feel that, if the documentation is a separate file,
>     Jim> programmers will be discouraged from writing docs, whereas,
>     Jim> if the documentation were mingled with the source, then
>     Jim> programmers would naturally write docstrings as they go
>     Jim> along?
> 
>  No...  but the function/variable documentation belongs in the code
>  next to what it's talking about.

I feel that it will make a difference. My span of attention is limited to
what is right in front of me.

>  It occurs to me that you could have
>  specially marked up comments that are extracted also, so they'll be
>  inserted at the point of the @inserthere{comment:thisfile.c:identXX}.

There is a balance between flexibility and structure. More structure makes
things easier to read and more logical to write. Mind you, the arbitrary
insertion of comments would be a very easy way to do whatever you liked
and tagging the existing comments (mostly in .h files) with identifiers
could be a quick way to bolt together some code documentation. The more
I think about it, the more I like it.

	- Tel