Provide APIs in snowballs documentation
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.
Afficher les réponses par date
Hello, Adrien Pierard <pierarda@iro.umontreal.ca> writes:
(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.
GNU Guile (which is an interpreter) has "docstrings" similar to what Emacs Lisp has, i.e., (define (make-chbouib foo bar) "Return a chbouib made from @var{foo} and @var{bar}." ...) It's simple, and Snow's `define*' could surely be made to discard such docstrings when using a compiler---but even if it doesn't, having the string in here doesn't hurt since it has no effect. Thanks, Ludovic.
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
I think the first step should be informal strings to add type annotation or/and general description. We could then improve the way package information is displayed on the website. I don't think that having the package form is really useful. Instead I would imagine having a provide section that list the exported symbols with annotations if they exist. Now where should that information be? In the package form or directly in the code?
participants (4)
-
Adrien Pierard -
Jeremie Lasalle Ratelle -
ludo＠gnu.org -
Matthew Martin