Re: Scheme file docstring format

[Michael Livshin]

Neil Jerram <address@hidden> writes:

>     Moi> [ what is occupancy? ]
> 
> Sorry!  I just meant the memory required to store the docstrings as
> part of loaded code.

duh!  don't be sorry, I was obviously being dumb.

but occupancy is an "easily" solvable problem (i.e. a SMOP), anyway.

;;-----------------------------------

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?

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

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.

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?

-- 
I knew you weren't really interested.