Re: [Chicken-users] Docstrings

[felix]

address@hidden wrote:
> 
> 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?

No, currently not. But I'm not sure wether the docstrings are really
useful at *runtime* (see below).

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

This should be easily doable using SRFI-10.

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

Or the compiler. The compiler has enough information to associate the
docstrings with the current procedure (and can take care of 
alpha-conversion issues, that is, the renaming of local variables).
Adding docstrings to be available at run-time is certainly convenient,
but if you want to extract the docs, you first would have to load
the file, with all side-effects caused by top-level expressions
that the code may bring... :-(
So let's better do that off-line.

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

I will remind you of that when the time comes... ;-)

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

There exist several ways of doing computation during compile-time. 
You can have macros, secondary-macros (don't ask), user-passes or
compiler extensions. This shouldn't be too hard to do.


cheers,
felix