[Snow-users-list] Provide APIs in snowballs documentation

Adrien Pierard pierarda at iro.umontreal.ca
Mon Jun 2 12:22:33 EDT 2008


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.


More information about the Snow-users-list mailing list