[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
documentation slot option
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.
(defclass foo ()
((x :reader foo-x
:documentation "the x slot stores the x position")))
would be equivalent to
(defclass foo ()
(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>
DEFCLASS needs to permit a slot option of the form:
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:
#+(OR TI ...) ; implementations that I happen to know accept this
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?