Re: Documentation procedure

[Dirk Herrmann <dirk at ida dot ing dot tu-bs dot de>]

On 6 Dec 1999, Per Bothner wrote:

> Keith Wright <kwright@tiac.net> writes:
> 
> > I propose a procedure:
> > 
> > (DOCUMENT-VALUE string value)
> >   -- attach string to the value in such a way that
> > the various auto-documentation procedures can get it
> > back again.  Return the value.
> 
> How about:
>         (documentation VALUE)
>         Returns documentation string associated with VALUE
>         (usually a procedure).
> 
>         (set! (documentation VALUE) DOC-STRING)
>         Associate the documentation string DOC-STRING with VALUE.

I like both ideas, and, obviously, they can both be provided.  The idea
from Per is nice due to the consistency with the generalized set! in
guile.  It allows to provide documentation in a different file, or
even change it on the fly (altough I'm not sure if the latter is
beneficial, but you don't have make use of it).

However, Keith's approach can be very nicely integrated when defining new
values and creating procedures.  This is the approach that would probably
be encouraged.  The nice thing about this is, that you can even document
temporary objects, like
(some-function (document-value "foobar" (compute-some-value)))
This could be great for debugging!  Sometimes you were lucky, if you knew
when and where some object was created.

So, I vote for integrating both approaches.  A little nitpicking, though:
1) instead of document-value, I'd prefer document-object
2) what about (define my-car car)?  I couldn't provide documentation for
   my-car that was different from the documentation of car.

The approaches shown above are clever, since they allow to document
objects, independent of whether there's a name for them or not.  Thus, 2)
is not an important complaint, since you could obviously do a (define
(my-car obj) (car obj)) instead and would get a new object that could get
a documentation string of its own.  However, it's a little overhead.  If
there's a good solution for 2) which doesn't compromise the 'niceness'(?) 
of the above ideas, great.  Otherwise, no problem for me.  Maybe some
additional 'document-binding' procedure (just a shot in the dark).

After you settle on a solution, this might be worth a SRFI.

Best regards,
Dirk