Re: :documentation

[David N Gray <Gray@DSG.csc.ti.com>]

It appears that the discussion of the :DOCUMENTATION slot option has
strayed away from what my original intent was.  The idea was that the
person who is writing a DEFCLASS should have a way to specify
documentation that explains what each slot is for, just as he currently
has a way to document the entire object.  What is actually done with the
doc string is really a programming environment issue rather than a
language issue.  It would be most useful for a data inspector where the
user could ask for a description of any of the slots of a class or
instance being examined, or for a documentation tool that automatically
generates descriptions of Lisp programs.  I suggested using it as the
doc string for the reader method since in most cases a description of
the slot would also be a reasonable description for what the reader
method is for, and the reader method does not have any documentation
otherwise.  This is like what we currently do with the :DOCUMENTATION
slot option of DEFSTRUCT (which I just today realized is not standard)
-- it becomes the doc string of the accessor function.  That is actually
more meaningful for a defstruct accessor since it documents the function
the user is calling, whereas for a CLOS reader it is the generic
function that you would really want to document.

So I would be content to have the standard say that the :DOCUMENTATION
slot option provides a way to document the slot, but that what, if
anything, is actually done with it is implementation dependent.

  -- David Gray