Re: Scheme file docstring format

[Michael Livshin]

Martin Grabmueller <address@hidden> writes:

> > * 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...

hmmm, perhaps I was just being panicky or something.  there's no
really hard problems that are specific to the manner in which the code
gets loaded into Guile, apart from extreme ugliness.  you'd have to
snarf a loaded file first, then slurp in the snarfed docs and
associate them with objects.  C-M-x is likewise unpleasant.

> > 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.

just so we don't start talking past each other, here's an example of
what I mean:

-----------
;;; file: tmp.scm

;; here, the docstring will be correctly snarfed and associated with
;; the name `foo'
(define (foo x)
  "I document foo"
  ...)

;; here we have no docstring
(define bar foo)

-----------
guile> (load "tmp.scm")
guile> (documentation foo)
"I document foo"
guile> (documentation bar)
#f
-----------

is that the behaviour you want?  'cause I don't.

> 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
> information.

yep.  this is orthogonal to the question whether the docs are snarfed
by some tool or in the course of the regular `read'.

> 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."
>       ...)

of course.  but you are critisizing a (badly) contrived example.  the
point was that the user may (and will) legitimately want to define
potentially documented objects using syntax other then `define'.
[s]he of course can arrange for the syntax to require explicit
documentation, but it still won't be recognized by any snarfer tool.

> 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).

even a mail message about semantics is pretty hard to generate. ;)

-- 
Perhaps it IS a good day to die; I say we ship it!
                                        -- Klingon Programmer