documentation

[Dick Gabriel <RPG@SAIL.Stanford.EDU>]

I have 2 questions about the :documentation slot option and a comment.

In the formulation proposed, there is no indication whether the
:documentation slot option is inherited like :initform or acts like
:reader. I presume since it doesn't specify a characteristic of the slot
it acts like :reader.  Yes?

And, if so, should the presence of :documentation in a slot where nothing
like :reader appears signal an error or simply be ignored?

The comment is that :documentation is a cruddy name for this option.
If someone simply reads the syntax description for DEFCLASS there is
no doubt he will believe it is part of some hairy documentation for the
entire class or for the slot.

This example (provided with the synposis I got) is misleading:

           (defclass foo ()
             ((x :reader foo-x
                 :reader bar-x
	         :writer (setf foo-x)
	         :documentation "the x slot stores the x position")))

Do you intend for the documentation of a method to only mention what the
slot is? Or would you expect to see:

           (defclass foo ()
             ((x :reader foo-x
                 :reader bar-x
	         :writer (setf foo-x)
	         :documentation "reader/writer for the x position")))

This points out another problem, which is that someone might want to have
different documentation strings for readers and writers. So why not
:accessor-documentation, :reader-documentation, and :writer-documentation?

I wouldn't mind dumping this one. Do we imagine the Cleanup committee will
never touch CLOS?

			-rpg-