Re: Documentation

[Michael Livshin]

Neil Jerram <address@hidden> writes:

> I can see the need for documenting a particular binding rather than a
> symbol, I'm just not sure how one can implement this.

(with-waving-hands

(help foo)
  ==macroexpand==>
(let ((handle (hashq-get-handle (module-visible-bindings (current-module))
                                'foo)))
  (if (not handle)
      (error 'wha? "who is this ~A you are talking about?" 'foo)
      (let ((binding-doc (documentation handle))
            (object-doc (documentation (cdr handle))))
        (if binding-doc
            (display-binding-doc (current-module) (car handle) binding-doc))
        (if object-doc
            (display-doc (cdr handle) object-doc)
            (error 'no-help "life is hard")))))

) ;with-waving-hands

> Can you make the idea a little more concrete, though, by giving an
> example of the use of #{...}# and indicating what this read syntax
> would expand to?

something like this:

(define (foo ...)
  #{ foo: do stuff }#
  ...)

upon seeng the #{ prefix, the reader gets all excited, reads the text
up to }# and does this:

(%store-string " foo: do stuff ")

this has the effect of storing the doc text in the database and
returns a little smob that identifies this text.

after that the function (if we would somehow print its source) would
look like this:

(define (foo ...)
  #<string handle (key: 0x42)>
  ...)

where the string handle is the abovementioned little smob that
contains the key and remembers to remove the string from the database
upon its death.

it should probably print as the text, too, so you would actually have
no way to see the #<string handle...> thing.

>     Michael> this does mean that in order to generate the chapter
>     Michael> about, say, regexps, you'll have to actually load the
>     Michael> regexp module into Guile.  which may be a problem...
> 
> Not a problem IMO.

not a problem if all modules are written in such a way that mere
loading them doesn't cause nasty side effects.

-- 
Parenthesize to avoid ambiguity.