From d6c687d16cb67665464e3995e574209f22b5e967 Mon Sep 17 00:00:00 2001
From: Simon Cruanes <simon.cruanes.2007@m4x.org>
Date: Sat, 14 Sep 2019 10:07:11 -0500
Subject: [PATCH] doc: use mdx to update the readme (and test)

---
 README.md       | 67 +++++++++++++++++++++++++++++++++++++++++++++++++
 dune            | 10 ++++++++
 ezcurl-lwt.opam |  1 +
 src/sync/dune   |  1 +
 4 files changed, 79 insertions(+)
 create mode 100644 dune

diff --git a/README.md b/README.md
index e3920e0..b18600e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,70 @@
 # EZCurl
 
 A simple wrapper around OCurl, for easy tasks around http.
+
+## Installation
+
+- for the synchronous library: `opam install ezcurl`
+- for the lwt-baed library: `opam install ezcurl-lwt` (depends on `ezcurl`)
+
+## Usage
+
+### Synchronous API
+
+The library lives in a module `Ezcurl`, which wraps `Curl.t` with functions
+such as `get` that combine many different low level API calls into one.
+It also follows redirections by default, and returns a `Ezcurl.response`
+object that contains the body, headers, and error code.
+
+```ocaml
+# #require "ezcurl";;
+# let url = "https://curl.haxx.se/";;
+val url : string = "https://curl.haxx.se/"
+# let res = Ezcurl.get ~url ();;
+val res : (Ezcurl_core.response, Curl.curlCode * string) result =
+  Ok
+   {Ezcurl_core.code = 200;
+    headers =
+...
+# let content = match res with Ok c -> c | Error (_,s) -> failwith s;;
+val content : Ezcurl_core.response =
+  {Ezcurl_core.code = 200;
+   headers =
+...
+
+# content.code;;
+- : int = 200
+```
+
+
+### Lwt API
+
+Using `ezcurl-lwt`, a module `Ezcurl_lwt` becomes available, with
+functions that are similar to the ones in `Ezcurl` but are non blocking.
+This makes it easy to run several queries in parallel:
+
+```ocaml
+# #require "ezcurl-lwt";;
+# let urls = [
+  "https://en.wikipedia.org/wiki/CURL";
+  "https://en.wikipedia.org/wiki/OCaml";
+  "https://curl.haxx.se/";
+  ];;
+val urls : string list =
+  ["https://en.wikipedia.org/wiki/CURL";
+   "https://en.wikipedia.org/wiki/OCaml"; "https://curl.haxx.se/"]
+
+# open Lwt.Infix;;
+# let codes =
+    List.map (fun url -> Ezcurl_lwt.get ~url ()) urls
+    |> Lwt_list.map_p
+    (fun fut ->
+      fut >>= function
+      | Ok r -> Lwt.return r.Ezcurl_lwt.code
+      | Error e -> Lwt.fail (Failure "oh no"))
+  ;;
+val codes : int list Ezcurl_lwt.io = <abstr>
+
+# codes;;
+- : int list = [200; 200; 200]
+```
diff --git a/dune b/dune
new file mode 100644
index 0000000..c72215c
--- /dev/null
+++ b/dune
@@ -0,0 +1,10 @@
+
+(alias
+ (name runtest)
+ (package ezcurl-lwt)
+ (deps README.md)
+ (action
+   (progn
+     (run ocaml-mdx test %{deps})
+     (diff? %{deps} %{deps}.corrected))))
+
diff --git a/ezcurl-lwt.opam b/ezcurl-lwt.opam
index afecf6f..5a2d523 100644
--- a/ezcurl-lwt.opam
+++ b/ezcurl-lwt.opam
@@ -18,6 +18,7 @@ depends: [
   "lwt"
   "dune" {build}
   "odoc" {with-doc}
+  "mdx" {with-test}
   "ocaml" { >= "4.03.0" }
 ]
 tags: [ "curl" "web" "http" "client" "lwt" ]
diff --git a/src/sync/dune b/src/sync/dune
index 7b01be1..399c4f3 100644
--- a/src/sync/dune
+++ b/src/sync/dune
@@ -1,4 +1,5 @@
 (library
  (name ezcurl)
+ (public_name ezcurl)
  (flags :standard -warn-error -32)
  (libraries curl ezcurl.core))