On 9/26/10 11:29 AM, Dieter Kaiser wrote:
> Because we do not have a technical documentation of Maxima internals, I
> have started to write some documentations of functions I have worked on.
> The following examples try to document the functions PLS, ADDK, EXPTA,
> and EXPTB in simp.lisp. I have taken the Common Lisp HyperSpec as a
> guide to document the functions.
>
> I am interested to add the documentations to the project. We might add
> it to the Lisp files (the documentation might be to verbose) or we start
> to add a technical documentation in a TEXI format.
>
> Opinions or suggestions?
>
I think this is a great idea. I would certainly like the documentation
to be in the Lisp files. I think that's more likely to be up-to-date
than having the documentation in some other file.
Also, my personal wish-list item would be to have docstrings for the
functions. They don't have to be as elaborate as the comments you've
proposed, but a simplified version would be awful nice when you want to
use the function but forget exactly what the arguments are or forget
exactly what it does. Yes, I can look up the source code, but I'm more
likely to remember the name of the function than the file the function
lives in. :-)
Oh, this is not saying that you, Dieter, needs to add the docstrings. I
can do that, and I hope others can if there is nice documentation for
the functions already.
Ray