[Chicken-users] Docstrings

[tonyg]

Felix, I agree with your earlier posting about (extend-procedure) - I
think that having a property-list on procedures for things like
docstrings, parameter-lists, maybe even source-code, would be really
useful.

Are there namespace-clash issues present or foreseeable?


Also, I really like the way Javadoc and Doxygen work with allowing you
to embed tags in the documentation. We could go for something low-tech
like

(define (myfn)
        "Does <a href="/stuff/index.html">some stuff</a>."
        ...)

*or* we could maybe go for something a little cooler ;-) like

(define (myfn)
        #doc("Does" (a (@ (href "/stuff/index.html")) "some stuff") ".")
        ...)

ie. embedding arbitrary (S)XML as the docstring! (Don't offhand know
how easy this would be for Chicken to parse, or whether it's
compatible with the usual reader-macro setup...)

Then a hypothetical offline-documentation tool could grovel over code,
extracting all the #doc() forms, wrapping them up in skeleton (S)XML,
and sending the whole thing through a stylesheet of some kind and out
to TeX/HTML/whatever...

If support for the raw syntax for documenting scheme entities was put
into chicken, I'd make it a priority to spend time going through all
the code in the system putting in appropriate docstrings.


(... maybe instead of #doc(), ie a readermacro, a normal macro would
suffice. In fact, that might be a better way of doing it: that way you
don't need to change chicken at all, you just have your
(documentation) macro write appropriate entries out to file at compile
time... hmm, means the documentation isn't so interactive anymore
though... Oh wait, also, how would the (documentation) macro know
which function it was currently documenting? There's no way to get at
the forms enclosing the macro... doh. There goes that idea.)

Tony
-- 
Monkeys high on math -- some of the best comedy on earth
        - Tom Lord, regarding comp.lang.scheme