On 7/17/06, Raymond Toy <raymond.toy at ericsson.com> wrote:
> I think it would be rather nice. Having used cmucl/sbcl's DESCRIBE
> function or emacs apropos/describe, it's very handy to be able to
> provide your own documentation without having to learn how to write
> texinfo files. In lisp, I just add the appropriate docstring, and I
> have documentation.
In the indexing scheme I'm working on, I'll try to leave a hook to
accomodate user-defined descriptions for when we figure out how
to expose that functionality.
> In fact, if I knew how, I'd want the documentation
> for every maxima function or variable to be in the function/variable
> itself, instead of in some separate file.
Well, this is problematic. (1) Maxima functions are often not associated
with a function of the same name, or any single function for that matter.
(2) Even if Maxima docs were implemented with doc strings,
it doesn't obviate the need for some kind of formatting markup.
(3) When docs are embedded in the source code, touching the
docs means touching the source files. Then when you try to trace
the history of some file you have to disentangle the two kinds of
changes. (4) Where do we put translations into Spanish, etc?
(5) What's important to users is generally different from what's
important to programmers. Trying to smash both into the source
code seems messy; source code should document stuff that's
important to programmers.
> (Actually, I'd like if even the internal maxima functions included
> docstrings. It makes the core size bigger, but I think the benefits
> outweigh the cost.)
Comments or doc strings in the Lisp code makes sense to me.
I've often wondered about zl-delete etc myself.
Robert