[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Chicken-users] Docstrings
From: |
felix |
Subject: |
Re: [Chicken-users] Docstrings |
Date: |
Thu, 15 Aug 2002 00:58:21 +0200 |
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