Re: Scheme file docstring format

[thi]

[old thread alert!]

   From: Neil Jerram <address@hidden>
   Date: 18 Feb 2001 20:08:55 +0000

   The way I see it, identifier visibility, as managed by the module
   system to resolve references in code, automatically determines the
   visibility of the corresponding docstring.

   [examples: `(help acons)' and `(apropos "acons")']

   `help' (and similarly `apropos') already do lookups like this.  I
   don't see the need for anything clever at the snarfing stage.

quite right.  i suppose i was imagining some scenario where one would
like to play with the docstring file w/o using `help' or `apropos'.
however, that seems pretty stupid upon second thought.

       thi> if docstrings are stored/accessed using the same mechanisms
       thi> to resolve module references, maybe the `define-module' form
       thi> and the value of applying `module-public-interface' should be
       thi> considered food for the snarfer as well.  (an
       thi> interface-oriented snarfer would be immediately useful for
       thi> GUMM [he says selfishly].... :-)

   I really don't understand; I'd like to, though, especially as you say
   it would be useful for GUMM.  Please explain in more detail.

this was kind of along m.livshin's theme of integrated reader.  since
snarfing involves (character) reading, i was voicing desire to get more
info (module dependency graph) out of the process.  it seems sort of
wasteful to write use2dot-style and snarfer-style programs, both which
must fundamentally traverse the source file characters.  this is the
one-pass-does-everything vs lots-of-efficient-little-passes argument.

(begin hand-waving here.)  the middle ground is to write a top-level
"analysis" source walker that can be invoked in different ways:

 grok --docs *.c *.scm  => docstrings to procedures.txt
 grok --mdep *.c *.scm  => module graph info to module-deps.dot
 grok --proc *.c *.scm  => procedure signatures
 grok --comp *.c *.scm  => hobbit-processed .so files
 grok --full *.c *.scm  => all of the above

this is needless complication if the goal is simply snarfing docstrings,
but nice if the goal is analyzing code (w/ useful by-product some
docstrings).  that's where the GUMM reference comes in -- modules in
GUMM will be extensively analyzed.

anyway, no worries.  more spew below...

       thi> most useful would be some flexibility in what constitutes
       thi> snarfable input.  certainly we can mandate files distributed
       thi> w/ guile to have a certain format, but it would be nice to be
       thi> able to snarf other formats which may be regular in their own
       thi> way albeit not strictly conforming.  the nice hack would be
       thi> to heuristically determine which snarfing method to use given
       thi> a large-enough set of never-before-seen modules...  anyway,
       thi> for an indexing framework implementation, check out imenu.el
       thi> in your local emacs installation.

instead of accepting, say:

;; @ l-t-u-a-e -- a nice constant
;;
(define l-t-u-a-e 42)

and rejecting (or not recognizing):

;; l-t-u-a-e
;; a nice constant
(define l-t-u-a-e 42)

it would be nice to be able to parameterize the snarfer to understand
both, and allow specification of other formats (as long as they are
regular).  something like:

(define-snarfer-parms guile-standard
  "\n;;"        ; doc start re
  ";;\n;;"      ; doc end re
  "@"           ; some trigger char or other
  (lambda ()    ; sig proc
    (read first-line)))

(define-snarfer-parms other-library-we-like-but-didnt-author
  "\n;;"        ; doc start re
  "^[^;]"       ; doc end re
  #f            ; some trigger char or other
  (lambda ()    ; sig proc
    (string-append (read first-line) (read second-line))))

shell> grok --docs --style guile-standard 
shell> grok --docs --style other-library-we-like-but-didnt-author

the nice hack would be to generate snarfer parms automatically....

i like the discussion about snarfing docstrings after guile is built.
using guile to do this job is vaguely satisfying, since all the above
ideas are more easily realized than w/o.  slow startup speed is not a
big deal at build-time, IMHO.  as for embedded guile users, Real
Programmers don't read docstrings anyway.  :->

thi