[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