Re: 0.14-030715 - defgeneric is not preserving doc-strings

On Fri, 1 Aug 2003, Ram Krishnan wrote:

> Any doc-string passed into the (:documentation ..) option of a
> defgeneric form is not being preserved as the 'function documentation
> of the generic function symbol.

You're right that this is a bug, but it should also be possible
to call (e.g.) ENSURE-GENERIC-FUNCTION-USING-CLASS with a
:DOCUMENTATION argument.

? (trace make-instance)
NIL
? (defgeneric foo (x) (:documentation "A Doc string"))
 Calling (MAKE-INSTANCE #<FUNCALLABLE-STANDARD-CLASS STANDARD-GENERIC-FUNCTION> :NAME FOO :LAMBDA-LIST (X) :METHOD-COMBINATION #<STANDARD-METHOD-COMBINATION STANDARD> :DOCUMENTATION "A Doc string")
 MAKE-INSTANCE returned #<STANDARD-GENERIC-FUNCTION FOO (Non-Global)  #x3542FA66>
#<STANDARD-GENERIC-FUNCTION FOO #x3542FA66>
? (documentation * t)
NIL

We can see from the trace output above that MAKE-INSTANCE is being called
with the correct :DOCUMENTATION argument, but it's either ignoring it
or otherwise failing to handle it correctly.

Fortunately, we can use the MOP to fix this.

(defmethod shared-initialize :after ((gf generic-function) slot-names
				     &key
				     (documentation nil doc-p)
				     &allow-other-keys)
  (declare (ignore slot-names))
  (when doc-p
    (if documentation (check-type documentation string))
    (set-documentation gf t documentation)))

(As you noted, CCL::SET-DOCUMENTATION turns itself into #'(SETF DOCUMENTATION)
later in the bootstrapping sequence.)

I'm not 100% sure that the above definition is correct; it's possible
that we'd always want to treat an unsupplied :DOCUMENTATION arg as if
it'd been supplied as NIL.