I get the impression that at least six different kinds of documentation
are being talked about here, each of which has different requirements:
1) Systematic documentation for users. There might be a chapter on the
various ways to pull apart Maxima expressions (part, inpart, pickapart,
etc.) and how to use them. The existing texi files have a bit of this
kind of material, though most of it is just reference material in
alphabetical order, which is really type 2:
2) User reference documentation on individual functions. For example,
how do you use the Part function, what are its arguments, and are there
any global variables that it depends on or sets? This should
cross-reference the systematic documentation.
3) Systematic documentation for implementors of Maxima. This would have
a chapter on internal representations, conventions for using them,
utilities, and the relationship between the internal format and the
usual input and output formats. Other chapters might cover how
simplification works and how to write your own SIMP routines, how to use
ASKSIGN and company, etc. Some of this material (incongruously) exists
in the texi files.
4) Reference documentation for implementors of other parts of the system
who might want to use a function. In the case of Part, it would
probably say "Part should almost never be used by Lisp programs;
instead, they should analyze expressions themselves; see Chapter 3 of
the Maxima implementors' manual." This is the usual role of docstrings.
In my opinion, only a relatively small number of generally-useful
functions (e.g. Alike1, Mul, Coeff, etc.) cry out for this kind of
documentation. Type (3) documentation is far more important than adding
a docstring to every function in Maxima.
5) Documentation for maintainers of that particular function or module.
This is usually done with inline documentation (semicolon comments), not
docstrings. This is where information on the weird and wonderful uses
of Special variables and so on belongs (except when external users need
to know about it).
6) Cross-references, who calls what, who uses what global variable, etc.
Very useful for people maintaining that code, and writing type (5)
documentation. This really needs to be a dynamic tool, not a static
listing. In the absence of the better things being proposed, I use
tags-search and tags-occur pretty heavily.
In addition to documentation, it would be nice to have some systematic
way of including test cases at the function and module level.
Currently, we only have system-level tests (the Test directory). Tests
can be useful not only for actual testing, but also for reminding
maintainers of difficult cases.
-s