I agree with everything...
Considering all facts (nobody has the time or motivation to write
long 'manuals' about extending maxima) I still think the best way to
go about it is to require each lisp function to have a doc string
added, explaining what it does in a few sentences. Fateman pointed
out that docstrings get included into the binary, but with the
abundance of space available today I don't think this is an issue -
and will become less of an issue each year..
Why I think docstrings are the best way to go about it:
- it doesn't take much effort to equip functions with a two sentence
doc string (so the developers will actually do it)
- the documentation is visible when browsing source code
- the same documentation can be read with 'describe'
- the same documentation can be used to generate html documentation with
http://common-lisp.net/project/cldoc/ or
http://common-lisp.net/project/tinaa/
The way I see it, it's the least amount of work with the biggest
payoff (compared to code comments or written documentation)
Of course code comments are also welcome, but are only visible when
browsing source code and are hard to be 'required' in an uniform way...
I might add that much of the newer code is documented nicely, but not
in an uniform way (text files, code comments...). I think the
requirement to add (short) doc strings to each function in Maxima,
would provide the best uniform documentation across Maxima, with the
least amount of work.
There are some documents describing Maxima internals (Fateman gave a
link some time ago), but we would need to gather these resources in
one place (Maxima's web site?).. Also a lot of posts on the mailing
list describe Maxima's internals, but again, this should be condensed
into a few text files and made easily available.
Regards,
Ziga