>>>>> "Richard" == Richard Fateman <fateman at cs.berkeley.edu> writes:
Richard> I don't know if the nature of the storage for lisp
Richard> docstring data is mandated.
Richard> There is a (setf (documentation 'foo 'bar) "stuff")...
Richard> In lisp
Richard> -- perhaps it can be implemented out of core.
Yes, I guess it can be out of core, and in emacs it is. But the point
is that it's with the source code, not in some totally disconnected,
manually maintained file. Yes, if you use (setf documentation), then
the documentation is not necessarily with the function itself, but I
really haven't seen much of that, and the few cases I have, the
function is very close to the (setf documentation), and it was always
for fairly esoteric uses.
Of course, docstrings do not make a good manual. You need a real
editor to do that, but having docstrings makes the programmers job
easier because the documentation for that function is right there with
the function. I often forget what zl-delete means and how it differs
from CL delete, so I have to grep around everytime to find the
function and study it to figure it out. A docstring would be so much
nicer. (Of course, this isn't a maxima user-level function, but the
idea is the same.)
Richard> I think it would be good to add documentation; I find
Richard> myself hesitant about some of this impulse because
Richard> documentation added by someone who does not in fact know
Richard> much about the function being documented can be
Richard> misleading. We
That's always a problem, but I think the greatest hurdle is getting
*any* documentation. Once something is written, it's easier to fix it
than to create it.
Ray