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@iro.umontreal.ca wrote:
Hi!
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) ... code ... (documentation* (function1 (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")) (function2 ...))
Good? Bad? Ugly?
Cheers,
P!
-- "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 wrong. _______________________________________________ Snow-users-list mailing list Snow-users-list@iro.umontreal.ca https://webmail.iro.umontreal.ca/mailman/listinfo/snow-users-list