From 760e0cb2d7c2ea7aee0bc07d4355447e15c26245 Mon Sep 17 00:00:00 2001
From: Torben Ewert <torben@ewert-online.com>
Date: Tue, 5 May 2020 20:35:00 +0200
Subject: [PATCH] TASK: Add Documentation

---
 Readme.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 123 insertions(+), 4 deletions(-)

diff --git a/Readme.md b/Readme.md
index ff30208..b5a4c7e 100644
--- a/Readme.md
+++ b/Readme.md
@@ -1,6 +1,22 @@
+# Table of contents
+
+- [What is it?](#what-is-it)
+- [What state is it in?](#what-state-is-it-in)
+- [How do I install it?](#how-do-i-install-it)
+- [API](#api)
+  - [Methods](#methods)
+  - [Query Strings](#query-strings)
+  - [Form Data](#form-data-todo)
+  - [Headers](#headers)
+  - [Response Types](#response-types)
+  - [Sending a Request](#sending-a-request)
+  - [Cancelling Requests](#cancelling-requests)
+  - [Complete Example](#complete-example)
+- [Credits](#credits)
+
 # What is it?
 
-Hermes is a Bucklescript library enabling http-requests over XMLHttpRequests.
+Hermes (the name is subject to change) is a Bucklescript library enabling http-requests over XMLHttpRequests.
 
 # What state is it in?
 
@@ -28,9 +44,106 @@ Then add `@space-labs/hermes` as a dependency to `bsconfig.json`:
 ]
 ```
 
-# How do I use it?
+# API
+
+### Methods
+
+```reason
+Hermes.Method.get("https://domain.com/");
+Hermes.Method.post("https://domain.com/");
+Hermes.Method.put("https://domain.com/");
+Hermes.Method.patch("https://domain.com/");
+Hermes.Method.delete("https://domain.com/");
+Hermes.Method.head("https://domain.com/");
+Hermes.Method.options("https://domain.com/");
+```
+
+### Query Strings
+
+```reason
+client->Hermes.QueryString.set([("key", "value"), ("key2", "value2")]);
+client->Hermes.QueryString.add("key", "value");
+client->Hermes.QueryString.remove("key");
+```
+
+### Form Data (TODO)
+
+```reason
+/*
+ Probably like this
+ client->Hermes.FormData.set([("key", "value"), ("key2", "value2")]);
+ client->Hermes.FormData.add("key", "value");
+ client->Hermes.FormData.remove("key");
+*/
+```
+
+### Headers
+
+```reason
+client->Hermes.Header.set([("key", "value"), ("key2", "value2")]);
+client->Hermes.Header.add("key", "value");
+client->Hermes.Header.remove("key");
+```
+
+### Handling Responses
+
+The datatype of the response is based on the currently set `ResponseType` (`option(string)` by default).
+
+```reason
+client->Hermes.onLoad(response => {
+  switch (response) {
+  | Ok(Some(data)) => Js.Console.log(data)
+  | Ok(None) => Js.Console.info("Response was empty")
+  | Error(message) => Js.Console.error(message)
+  }
+});
+```
+
+### Response Types
 
-### Example
+If you want to change the `ResponseType`, you have to do it **before** the `onLoad`. If you set it afterwards, your
+`onLoad` will be removed (because it would assume a wrong type signature).
+
+| ResponseType | PayloadType                          |
+| ------------ | ------------------------------------ |
+| Text         | option(string)                       |
+| Json         | option(Js.Json.t)                    |
+| Document     | option(Dom.document)                 |
+| ArrayBuffer  | option(Js.Typed_array.ArrayBuffer.t) |
+
+```reason
+client->Hermes.ResponseType.setText; // default
+client->Hermes.ResponseType.setJson;
+client->Hermes.ResponseType.setDocument;
+client->Hermes.ResponseType.setArrayBuffer;
+```
+
+### Sending a Request
+
+```reason
+client->Hermes.send;
+```
+
+### Cancelling Requests
+
+`Hermes.send` returns a function, with which you may cancel the current request. It has a signature of
+`option(unit => unit)`, so you dont't have to do anything when using it inside `React.useEffect`.
+
+```reason
+  /* React */
+  React.useEffect(() => {
+    Hermes.Method.get("https://domain.com/")->Hermes.send
+  });
+
+  /* Plain Reason */
+  let maybeCancel = Hermes.Method.get("https://domain.com/")->Hermes.send;
+  switch(maybeCancel) {
+    | Some(cancel) => cancel();
+    | None => ();
+  };
+```
+
+### Complete Example
 
 ```reason
 Hermes.Method.get("http://localhost:8081/")
@@ -42,7 +155,7 @@ Hermes.Method.get("http://localhost:8081/")
     ("email", "max@mustermann.de"),
   ])
 ->Hermes.Header.add("authorization", "Bearer 123")
-->Hermes.Event.onLoad(response => {
+->Hermes.onLoad(response => {
     switch (response) {
     | Ok(Some(data)) => Js.Console.log(data)
     | Ok(None) => Js.Console.info("No Response!")
@@ -51,3 +164,9 @@ Hermes.Method.get("http://localhost:8081/")
   })
 ->Hermes.send;
 ```
+
+## Credits
+
+[Request - Simplified HTTP client](https://github.com/request/request) for inspiration
+
+**@hgiraud** on Discord had some nice suggestions regarding the API
-- 
2.51.2