Documentation and error messages

[Scott E. Fahlman <Fahlman at Cmu-20c>]

Despite my earlier opposition to one-line documentation strings, I now
see the need for them.  I agree with Guy that we need short and medium
forms of built-in documentation for functions and short, medium, and
"return value" forms for errors.  These fit nicely into Moon's proposal
for documentation retrieval: in addition to having a DEFUN documentation
accessor, we would also have a SHORT-DEFUN.  (Actually, like many
others, I prefer FUNCTION and VARIABLE to DEFUN and DEFVAR, but that is
a separate issue.)

Guy's proposal for supplying these strings to the error forms sounds OK.
I worry about adding more hair to DEFUN.  Putting the doc string into
DEFUN is cute, and it has had the psychological effect of encouraging
people to use these strings, but it may be time to create a separate
documentation-defining form.  With enough good examples and social
pressure -- nothing gets into the yellow pages unless every user-visible
function and special variable is documented -- we would still get
compliance.

(document foo
  'short-function
"Short documentation for FOO goes here."
  'function
"Long documentation for FOO goes here and just to make this longer
I will include this useless extra clause."
  'algorithm
"Uses the bubbly-quick-foo algorithm, which is O(n log n).  See Knuth,
volume 5.  For small N, you are better off using BAR."
  'bugs
"With an argument of 0, destructively rewinds the disk.")

(defun foo ...)

We probably don't want to go for this many flavors of doc right now, but
it gives us some room to grow in the future.  Of course, for awhile we
would support embedded doc strings in DEFUN as a compatibility measure.
The embedded string would be FUNCTION (or DEFUN) documentation.

-- Scott