added documentation

README.md

@@ -3,6 +3,14 @@
 A minimal request library for and in zepto.
 Requires at least version 0.9.2.
 
+Documentation can be generated with `zeps`.
+
+## Installation
+
+```
+zeps install hellerve/request
+```
+
 ## Usage
 
 This library exposes a few endpoints for simple

module.zp

@@ -1,5 +1,5 @@
 #{:name "request"
-  :version "1.0.0" 
+  :version "1.0.1"
   :license "GPLv2"
   :tests []
   :type :library

request.zp

@@ -15,12 +15,30 @@
   (FOLLOW-REDIRECTS #f)
 
   (set-buffer-size (lambda (nsize)
+    "sets the buffer size of the socket buffer.
+
+     params:
+      - nsize: an integer denoting the size
+     complexity: O(1)
+     returns: the new value"
     (set! BSIZE nsize)))
 
   (set-default-headers (lambda (headers)
+    "sets the default headers (normally only the user agent is set).
+
+     params:
+      - headers: a hashmap mapping header names to values
+     complexity: O(1)
+     returns: the new value"
     (set! DFLT-HEADERS headers)))
 
   (set-follow-redirects (lambda (flag)
+    "sets the flag whether the library should follow redirects.
+
+     params:
+      - flag: the boolean
+     complexity: O(1)
+     returns: the new value"
     (set! FOLLOW-REDIRECTS flag)))
 
   (end-request (lambda (res sock)
@@ -79,6 +97,15 @@
                   size)))))))
 
   (request (lambda (scheme path opts)
+    "performs a request to <par>path</par> (<par>scheme</par> is a string denoting the method).
+     Options are given as the optional argument <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - scheme: the method type (e.g. <zepto>\"PUT\"</zepto> or <zepto>\"DELETE\"</zepto>)
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (let* ((path (if (string:starts-with path "http://") (substring path 7 (length path)) path))
            (path (if (string:starts-with path "https://") (substring path 8 (length path)) path))
            (split (string:split path #\/))
@@ -119,16 +146,56 @@
               (loop (net:recv sock (min BSIZE (- len cur))) (++ bytes recvd) ncur len)))))))))
 
   (head (lambda (path . opts)
+    "performs a HEAD request to <par>path</par>. Options are given as the optional argument
+     <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (request "HEAD" path (get-from opts 0 #{}))))
 
   (get (lambda (path . opts)
+    "performs a GET request to <par>path</par>. Options are given as the optional argument
+     <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (request "GET" path (get-from opts 0 #{}))))
 
   (post (lambda (path . opts)
+    "performs a POST request to <par>path</par>. Options are given as the optional argument
+     <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (request "POST" path (get-from opts 0 #{}))))
 
   (put (lambda (path . opts)
+    "performs a PUT request to <par>path</par>. Options are given as the optional argument
+     <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (request "PUT" path (get-from opts 0 #{}))))
 
   (delete (lambda (path . opts)
+    "performs a DELETE request to <par>path</par>. Options are given as the optional argument
+     <par>opts</par>.
+
+     params:
+      - path: the resource to access
+      - opts: the options (accepted keys are <zepto>:headers</zepto> and <zepto>:body</zepto>)
+     complexity: O(1) (heavily dependent on the network and request/response)
+     returns: a hashmap with the keys <zepto>:headers</zepto>, <zepto>:body</zepto>, <zepto>:status</zepto>, and <zepto>:request</zepto>"
     (request "DELETE" path (get-from opts 0 #{})))))