[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Scheme file docstring format

From: Martin Grabmueller
Subject: Re: Scheme file docstring format
Date: Wed, 21 Feb 2001 12:27:09 +0100 (MET)

> From: Michael Livshin <address@hidden>
> Date: 21 Feb 2001 12:51:21 +0200
> I see people talking about various intricate details of snarfing info
> from Scheme files.  I don't see people addressing more fundamental
> questions concerning "snarfing" as a concept and its
> relevance/applicability to Scheme code.
> * what happens when you load a file into Guile?

I don't get that.  Do you mean what happens to docstrings when the
loaded file overwrites old definitions?

> * what happens when you do C-M-x on a function in Emacs?

I don't see the problem, too...  Sorry for being dumb...

> I think that any method of documenting Scheme code that we agree on
> _must_ work well in the above two situations.
> that's why I'm saying (not very clearly, alas, sorry about that) that
> any "tool" solution (i.e. some separate snarfer script) looks wrong to
> me.
> the actual syntax and placement of documentation text is less
> important, as long as the reader (a snarfer script or, as I see it,
> the `read' function) is able to see it and reliably associate it with
> the appropriate syntactic entity.
> it's also worth noting that a snarfer script would tend to associate
> documentation with names, not objects.  and this would be very wrong,
> too.

But aren't names syntactic entities, as you wanted to have the
docstrings attached to in the previous paragraph?  Names are very
important for humans, and humans tend to query information about
names, not objects, simply because they can't write objects down, or
click onto objects, but only identifiers.

Also, we could associate `documentation tags' with objects, so that
when the user asks about the documentation about an object, this tag
is used to query the documentation database for the required

> it's also worth noting that some people will no doubt want to write
> macros that work like this:
> ;; macro call
> (define-frob baz (a b c))
> ;; expansion
> (begin
>   (define baz-rtd (define-record-type #:fields '(a b c)
>                                       #:doc
>                                       "baz: a frob record type"))
>   (define (twiddle-baz obj)
>     "twiddle a baz frob."
>     ...)
>   ...)
> how would you snarf such things?

Hmmm.  Personally, I dislike such automatically generated docstrings.
They only give information which could be deduced (by the reader) from
well named identifiers.  Documentation like this makes me sick:

(define (bar-set! b v)
        "Set the bar b to v."

The user will want information which is harder to get, such as side
effects, unexpected behaviour, exceptions etc.  And documentation
about semantics is very hard to generate (if at all).

Martin Grabmueller              address@hidden  address@hidden on EFnet

reply via email to

[Prev in Thread] Current Thread [Next in Thread]