[Snow-users-list] Provide APIs in snowballs documentation
Matthew Martin
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>
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 at iro.umontreal.ca
> https://webmail.iro.umontreal.ca/mailman/listinfo/snow-users-list
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://webmail.iro.umontreal.ca/pipermail/snow-users-list/attachments/20080602/4be8c768/attachment.html
More information about the Snow-users-list
mailing list