On 9/27/10, Robyn Dawn Hannigan <jedi_robyn at xtra.co.nz> wrote:
> Robert, if this is done, and docs are embedded in source code,
> would you be interested in some automation for adding them there?
>
> The reason i ask is that if all functions, symbols whatever have docs in the
> same format then at least... it can later be parsed out and used separately.
I am certainly very much in favor of internal documentation,
but I don't see much value (and I do see a lot of trouble) in
figuring out a way to make it processable automatically.
Internal documentation is for Maxima hackers, and what are
they always looking at? Not a separate document.
User-level documentation has to be different. We do have a
separate format for that (texinfo) and that's OK.
We need some documents apart from the code that give
an overview of the simplification system, representations
of expressions, etc. But that can't be constructed from the
union of the documentation of functions and variables;
it has to be written separately.
I certainly understand the idea of preserving information for
future generations of hackers, but frankly I don't think the
format of it makes much difference. It is easy to put stuff
into comments, so let's just do it instead of spending
time working out another system.
FWIW
Robert Dodier