documentation slot option

[Gregor.pa@Xerox.COM]

One of the comments we received proposed a :documentation slot option.
This option would provide a documentation string for the automatically
generated :reader or :writer methods for the slot.

So:

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

would be equivalent to

(defclass foo ()
     ((x)))

(defmethod foo-x ((foo foo))
  "the x slot stores the x position"
  (slot-value foo 'x))


This is the actual comment we received:

    Date: Fri, 15 Apr 88 13:43 PDT
    From: David N Gray <Gray@DSG.csc.ti.com>
    
    Functionality comments:
    -----------------------
    
    DEFCLASS needs to permit a slot option of the form:
      (:DOCUMENTATION doc-string)
    Any implementation would be permitted to ignore this, but the
    standard should recommend that the specified doc-string should become the
    value to be returned by the DOCUMENTATION function for any reader methods
    created for the slot by the :READER or :ACCESSOR options.
    
    I recognize that an implementation is already permitted to support this as
    an extension, but since the use of documentation should be encouraged
    rather than made more difficult, I think it is unacceptable to require
    users to write code that looks like this:
    
       ...
       (:READER FOO)
       #+(OR TI ...) ; implementations that I happen to know accept this
       (:DOCUMENTATION "...")
       ...
    
    when it is trivial for an implementation to just ignore the option if it
    doesn't wish to support it.


I am mildly opposed to this because I think documentation strings are a
joke.  I am also mildy opposed because it isn't clear that the same
documentation string could be useful for all the automatically generated
methods for a slot.

It is well defined though, so we could go ahead and do it.

What do others think?
-------