jurl: add docs to jurl/mime

1 files changed, 35 insertions, 8 deletions

diff --git a/jurl/mime.janet b/jurl/mime.janet
index 852e6d2..1e07f35 100644
--- a/jurl/mime.janet
+++ b/jurl/mime.janet
@@ -1,6 +1,9 @@
 # wrapper around native/mime stuff
 (import jurl/native)
 
+(setdyn :doc
+        "Wrapper around native jurl functions to handle multipart mime form data.")
+
 (defn- mime-part
   [handle {:name     name
            :data     data
@@ -44,16 +47,40 @@
 
 # define a complete mime in one go
 (defn new
+  ````Generates a new multipart mime handle bound to `handle`.
+  Each part denotes a field using a struct that takes the following keys:
+  * name: the name of the field
+  * data: the contents of the field. Possible options are:
+    * `buffer|string`: raw data to use
+    * `mime`: the putput of a previous `new` call to use as subparts
+    * `[:bytes buffer|string]`: see buffer|string
+    * `[:file fname]`: the name of a file whose contents to use as a body.
+      Note that this automatically sets filename. You can set it back to null manually.
+    * `[:mime mime]`: see mime
+  * filename: the remote filename to use.
+    This is the only option that determines whether the form specifies a file upload or not.
+  * type: the content-type to use for the part.
+  * headers: any custom headers to include for this mimepart.
+  * encoder: the encoder to use.
+    Valid options can be seen in `curl_mime_encoder(3)`.
+
+  For example:
+  ```
+  (new {:name "data"
+        :data "a form"}
+       {:name "file"
+        :data [:file "local.json"]
+        :filename "remote.json"
+        :type "application/json"})
+  ```
+  Specifies a multipart form submission with two fields.
+  The "data" field submits "a form" in plaintext.
+  The "file" field submits the contents of the "local.json" file to the server
+  as if it was called "remote.json",
+  and specifies that it's the "application/json" mimetype.
+  ````
   [handle & parts]
   (def out (native/new-mime handle))
   (each part parts
     (mime-part (:addpart out) part))
   out)
-
-# example
-(comment (new {:name "data"
-               :data "a form"}
-              {:name "file"
-               :data [:file "local.file"]
-               :filename "remote.file"
-               :type "application/json"}))