We've been writing some code for creating a frame-based memory, and we'd
like to allow documentation strings on definition forms. For example, we'd
like to write:
(define-instance i-guy-steele-jr (c-person)
:documentation "The author of CLtL2")
My first thought was to use the documentation method; the above macro call
would (eventually) do something like:
(setf (documentation 'i-guy-steele-jr <type>) "The author of CLtL2")
According to (my understanding of) CLtL2 and the CL Hyperspec, what <type>
can be is limited to a certain set, and although implementations may allow
extensions, a particular implementation must signal an error if it doesn't
support that extension. Macintosh Common Lisp, which we are using,
apparently allows <type> to be any symbol, but I'd like this not to be
platform dependent.
My options seem to be:
1. use one of the existing types, probably VARIABLE,
2. define our own internal documentation system,
3. just ignore documentation slots (let them be like comments, and thus local
to the definition files).
Any other ideas?
--
Will Fitzgerald
Neodesic Corporation
··········@neodesic.com (Will Fitzgerald) writes:
>
> We've been writing some code for creating a frame-based memory, and we'd
> like to allow documentation strings on definition forms. For example, we'd
> like to write:
>
> (define-instance i-guy-steele-jr (c-person)
> :documentation "The author of CLtL2")
>
> My first thought was to use the documentation method; the above macro call
> would (eventually) do something like:
>
> (setf (documentation 'i-guy-steele-jr <type>) "The author of CLtL2")
>
...
>
> My options seem to be:
>
> 1. use one of the existing types, probably VARIABLE,
> 2. define our own internal documentation system,
> 3. just ignore documentation slots (let them be like comments, and thus local
> to the definition files).
>
> Any other ideas?
>
Use CLOS and get all of the above for free.
--
Marco Antoniotti
==============================================================================
California Path Program - UC Berkeley
Richmond Field Station
tel. +1 - 510 - 231 9472
··········@neodesic.com (Will Fitzgerald) writes:
> (setf (documentation 'i-guy-steele-jr <type>) "The author of CLtL2")
> According to (my understanding of) CLtL2 and the CL Hyperspec, what
> <type> can be is limited to a certain set, and although
> implementations may allow extensions,
I can't speak for CLTL2, but CLHS specifically says conforming
programs can extend the set of signatures on this generic function.
If you do so for a type defined by the system, you'll doubtless lose
(so I don't recommend dispatching on the name, but rather on the
object backing it up). The new documentation type T is designed
specifically for your needs--it effectively uses the representation
class as the dispatch key. I think the following is supposed to
work, though I admit I didn't test it because I didn't have a Lisp
available to test it in from where I am typing this:
(defclass foo () ((doc :initarg :doc :accessor foo-doc)))
(defmethod documentation ((what foo) (doctype (eql 't)))
(foo-doc what))
(defmethod (setf documentation) (new-doc (what foo) (doctype (eql 't)))
(check-type new-doc string "a documentation string")
(setf (foo-doc what) new-doc)
I'm fairly sure this was low on single every vendor's list of
priorities. Among other things, the change in the method signature
was an incompatible change and vendors hate making incompatible
changes for any other reason than "clear customer demand". So I won't
be surprised if this doesn't work in all implementations, but that's
just a compliance bug in the implementation if it doesn't. In that
case, send a bug report and I'm sure it'll be fixed eventually.
Moreover, I'm pretty sure if you don't send a bug report, some vendors
will conclude "no customer demand" and will continue to avoid that
irritating little incompatible change.