[Snow-users-list] Provide APIs in snowballs documentation
matt.a.martin at gmail.com
Mon Jun 2 15:05:54 EDT 2008
I don't much like having the documentation at the bottom so far away from
the actual defines, but I do like having more organized descriptions than a
single string. Perhaps a combination of the 2nd and 3rd examples?
Irregardless though, any kind of API documentation for snowballs would be
absolutely wonderful, even if it's just of the "foo => bar" sort.
On Mon, Jun 2, 2008 at 11:22 AM, Adrien Pierard <pierarda at iro.umontreal.ca>
> I'd like define* to behave a bit like CL, or some file to be written
> along with the snowballs, and have the API of functions displayed on the
> web site.
> By API, I mean some sort of informal type anotations.
> Example (from snowball digest):
> (define (digest-update-u32-be digest n))
> :: DATA NUMBER -> STRING
> I'd like to know whether is returns a sting, a vector of integers, a
> vector of strings representing hex numbers withoug having to install or
> worse, test it.
> One could either do
> (define* (function args)
> (annotation: "foo bar quux => dadidada")
> (frobnicate args))
> This annotation only lives at compile time, and is deleted afterwards
> from interpreted code, but gives enough information when parsed to
> generate some text for the web page or to the snowman.
> snowman --get-annotations snowball symbol
> => foo bar quux => dadidada
> Another idea would be to implement POD like documentation embedded at
> the end of a snowball, tp generate the whole documentation, like this:
> (define* foo bar)
> (type: "NUMBER -> SYMBOL -> ALCOHOL -> NUMBER")
> (complexity: "O(N^2) where N is the alcoholic proof of the third arg")
> (description: "This function computes the age of the captain"))
> Good? Bad? Ugly?
> "I am not a Church numeral; I am a free variable!"
> (The Scheme Underground)
> For every complex problem, there is a solution that is simple, neat, and
> Snow-users-list mailing list
> Snow-users-list at iro.umontreal.ca
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Snow-users-list