Prepare documentation for v2

thoth-org · Mar 4, 2020 · eb575c1 · eb575c1
1 parent b03a8c8
commit eb575c1
Show file tree

Hide file tree

Showing 3 changed files with 85 additions and 85 deletions.
diff --git a/docs/index.md b/docs/index.md
@@ -4,21 +4,19 @@ title: Thoth.Fetch
 
 [[toc]]
 
-:::info
-Documentation for beta versions can be found here:
+This documentation is for `Thoth.Fetch` v2, documentation for older versions can be found here:
 
-- [Version 2.0.0-beta-001](/Thoth.Fetch/versions/2.0.0-beta-001.html)
-:::
+- [Thoth.Fetch v1](/Thoth.Fetch/versions/v1.html)
 
 ## Usage
 
 Thoth.Fetch provides an easy to use API for working with [Fable.Fetch](https://github.com/fable-compiler/fable-fetch) and [Thoth.Json](https://mangelmaxime.github.io/Thoth/json/v3.html). It supports both manual and auto coders depending on your preferences.
 
-For each method, Thoth.Fetch provides a ***safe*** and ***unsafe*** version.
+For each method, it provides a **safe** and an **unsafe** version.
 
-We call ***safe*** a method which returns a `Result<'T, string>`.
+We call **safe** a method which returns a `Result<'T, FetchError>`.
 
-We call ***unsafe*** a method that will throw an exception when a coder fails.
+We call **unsafe** a method that will throw an exception when a coder fails.
 
 List of "unsafe" methods:
 - fetchAs
@@ -36,11 +34,46 @@ List of "safe" methods:
 - tryPatch
 - tryDelete
 
+### Successful request
+
+A request is successful if no [error case](#Errored-request) has been encounter. There is one exception to this rule which is `unit` request.
+
+In the case of `unit`, `Thoth.Fetch` will consider the request valid if it gets a result from the server. It means it doesn't validate the `body` content.
+
+It is useful if you want to send a request to the server and want to `ignore` the result.
+
+Example:
+
+```fsharp
+promise {
+    // ...
+    do! Fetch.post("https://my-servver.com/log", "Some data to log")
+    // or
+    do! Fetch.delete("https://my-servver.com/user/2")
+    // or
+    let! res = Fetch.delete("https://my-servver.com/user/2")
+    // res value is ()
+    // ...
+}
+```
+
+### Errored request
+
+`Thoth.Fetch` can return different errors:
+
+1. If an exception occured by preparing the request, you will get `PreparingRequestFailed` with the `exception` as an argument.
+
+1. If there was an error during the request execution, you will get `NetworkError` with the `exception` as an argument.
+
+1. If we received a result but the `statusCode` was not ok (outside of the range 200-299), you will get `FetchFailed` with the raw `response` as an argument.
+
+1. If we received a result but `Thoth.Json` decoding failed, you will get `DecodingFailed` with the error message as an argument.
+
 ## Manual coders
 
 ### Example
 
-#### Define your decoder
+#### Define your decoder, encoder, and extracoder
 
 ```fsharp
 open Thoth.Fetch
@@ -64,6 +97,19 @@ type Book =
               CreatedAt = get.Required.Field "createdAt" Decode.datetime
               UpdatedAt = get.Optional.Field "updatedAt" Decode.datetime }
         )
+
+    /// Transform JSON as Book
+    static member Encoder (book : Book)=
+        Encode.object [
+            "id", Encode.int book.Id
+            "title", Encode.string book.Title
+            "author", Encode.string book.Author
+            "createdAt", Encode.datetime book.CreatedAt
+            "updatedAt", Encode.option Encode.datetime book.UpdatedAt
+        ]
+
+let bookCoder: ExtraCoders = Extra.empty
+                             |> Extra.withCustom Book.Encoder Book.Decoder
 ```
 
 #### GET request
@@ -72,7 +118,7 @@ type Book =
 let getBookById (id : int) =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" id
-        return! Fetch.get(url, Book.Decoder)
+        return! Fetch.get(url, decoder = Book.Decoder)
     }
 ```
 
@@ -89,7 +135,7 @@ let createBook (book : Book) =
                 "createdAt", Encode.datetime book.CreatedAt
                 "updatedAt", Encode.option Encode.datetime book.UpdatedAt
             ]
-        return! Fetch.post(url, data, Book.Decoder)
+        return! Fetch.post(url, data, decoder = Book.Decoder)
     }
 ```
 
@@ -107,27 +153,25 @@ let updateBook (book : Book) =
                 "createdAt", Encode.datetime book.CreatedAt
                 "updatedAt", Encode.option Encode.datetime book.UpdatedAt
             ]
-        return! Fetch.put(url, data, Book.Decoder)
+        return! Fetch.put(url, data, decoder = Book.Decoder)
     }
 ```
 
 #### DELETE request
 
 ```fsharp
-let deleteBook (book : Book) =
+let deleteBook (book : Book) : JS.Promise<bool> =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" book.Id
-        // We need to pass `null` to send no data
-        // Otherwise, F# compiler can't resolve the overload
-        return! Fetch.delete(url, null, Decode.bool)
+        return! Fetch.delete()
     }
 ```
 
 ## Auto coders
 
-You need to help F# type inference to determine which type is expected.
+You need to help F# type inference determine which type is expected.
 
-Here are two ways to do it. There are other approaches but but these are simpler:
+Here is two ways to do it, more exists but thuse are the simpler:
 
 ### Type via the promise result
 
@@ -236,12 +280,10 @@ let updateBook (book : Book) : JS.Promise<Book> =
 #### DELETE request
 
 ```fsharp
-let deleteBook (book : Book) : JS.Promise<bool> =
+let deleteBook (book : Book) : JS.Promise<unit> =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" book.Id
-        // We need to pass `null` to send no data
-        // Otherwise, F# compiler can't resolve the overload
-        return! Fetch.delete(url, null)
+        return! Fetch.delete(url)
     }
 ```
 

diff --git a/docs/versions/2.0.0-beta-001.md → docs/versions/v1.md b/docs/versions/2.0.0-beta-001.md → docs/versions/v1.md
@@ -4,19 +4,21 @@ title: Thoth.Fetch
 
 [[toc]]
 
-:::info
-This documentation is for version **2.0.0-beta-001**, documentation for **stable** version can be found [here](/Thoth.Fetch/).
+:::warning
+Your are looking at **version 1** of Thoth.Fetch.</p>
+
+Please consider upgrading your project to a newest version.
 :::
 
 ## Usage
 
 Thoth.Fetch provides an easy to use API for working with [Fable.Fetch](https://github.com/fable-compiler/fable-fetch) and [Thoth.Json](https://mangelmaxime.github.io/Thoth/json/v3.html). It supports both manual and auto coders depending on your preferences.
 
-For each method, it provides a **safe** and an **unsafe** version.
+For each method, Thoth.Fetch provides a ***safe*** and ***unsafe*** version.
 
-We call **safe** a method which returns a `Result<'T, FetchError>`.
+We call ***safe*** a method which returns a `Result<'T, string>`.
 
-We call **unsafe** a method that will throw an exception when a coder fails.
+We call ***unsafe*** a method that will throw an exception when a coder fails.
 
 List of "unsafe" methods:
 - fetchAs
@@ -34,46 +36,11 @@ List of "safe" methods:
 - tryPatch
 - tryDelete
 
-### Successful request
-
-A request is successful if no [error case](#Errored-request) has been encounter. There is one exception to this rule which is `unit` request.
-
-In the case of `unit`, `Thoth.Fetch` will consider the request valid if it gets a result from the server. It means it doesn't validate the `body` content.
-
-It is useful if you want to send a request to the server and want to `ignore` the result.
-
-Example:
-
-```fsharp
-promise {
-    // ...
-    do! Fetch.post("https://my-servver.com/log", "Some data to log")
-    // or
-    do! Fetch.delete("https://my-servver.com/user/2")
-    // or
-    let! res = Fetch.delete("https://my-servver.com/user/2")
-    // res value is ()
-    // ...
-}
-```
-
-### Errored request
-
-`Thoth.Fetch` can return different errors:
-
-1. If an exception occured by preparing the request, you will get `PreparingRequestFailed` with the `exception` as an argument.
-
-1. If there was an error during the request execution, you will get `NetworkError` with the `exception` as an argument.
-
-1. If we received a result but the `statusCode` was not ok (outside of the range 200-299), you will get `FetchFailed` with the raw `response` as an argument.
-
-1. If we received a result but `Thoth.Json` decoding failed, you will get `DecodingFailed` with the error message as an argument.
-
 ## Manual coders
 
 ### Example
 
-#### Define your decoder, encoder, and extracoder
+#### Define your decoder
 
 ```fsharp
 open Thoth.Fetch
@@ -97,19 +64,6 @@ type Book =
               CreatedAt = get.Required.Field "createdAt" Decode.datetime
               UpdatedAt = get.Optional.Field "updatedAt" Decode.datetime }
         )
-
-    /// Transform JSON as Book
-    static member Encoder (book : Book)=
-        Encode.object [
-            "id", Encode.int book.Id
-            "title", Encode.string book.Title
-            "author", Encode.string book.Author
-            "createdAt", Encode.datetime book.CreatedAt
-            "updatedAt", Encode.option Encode.datetime book.UpdatedAt
-        ]
-
-let bookCoder: ExtraCoders = Extra.empty
-                             |> Extra.withCustom Book.Encoder Book.Decoder
 ```
 
 #### GET request
@@ -118,7 +72,7 @@ let bookCoder: ExtraCoders = Extra.empty
 let getBookById (id : int) =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" id
-        return! Fetch.get(url, decoder = Book.Decoder)
+        return! Fetch.get(url, Book.Decoder)
     }
 ```
 
@@ -135,7 +89,7 @@ let createBook (book : Book) =
                 "createdAt", Encode.datetime book.CreatedAt
                 "updatedAt", Encode.option Encode.datetime book.UpdatedAt
             ]
-        return! Fetch.post(url, data, decoder = Book.Decoder)
+        return! Fetch.post(url, data, Book.Decoder)
     }
 ```
 
@@ -153,25 +107,27 @@ let updateBook (book : Book) =
                 "createdAt", Encode.datetime book.CreatedAt
                 "updatedAt", Encode.option Encode.datetime book.UpdatedAt
             ]
-        return! Fetch.put(url, data, decoder = Book.Decoder)
+        return! Fetch.put(url, data, Book.Decoder)
     }
 ```
 
 #### DELETE request
 
 ```fsharp
-let deleteBook (book : Book) : JS.Promise<bool> =
+let deleteBook (book : Book) =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" book.Id
-        return! Fetch.delete()
+        // We need to pass `null` to send no data
+        // Otherwise, F# compiler can't resolve the overload
+        return! Fetch.delete(url, null, Decode.bool)
     }
 ```
 
 ## Auto coders
 
-You need to help F# type inference determine which type is expected.
+You need to help F# type inference to determine which type is expected.
 
-Here is two ways to do it, more exists but thuse are the simpler:
+Here are two ways to do it. There are other approaches but but these are simpler:
 
 ### Type via the promise result
 
@@ -280,10 +236,12 @@ let updateBook (book : Book) : JS.Promise<Book> =
 #### DELETE request
 
 ```fsharp
-let deleteBook (book : Book) : JS.Promise<unit> =
+let deleteBook (book : Book) : JS.Promise<bool> =
     promise {
         let url = sprintf "http://localhost:8080/books/%i" book.Id
-        return! Fetch.delete(url)
+        // We need to pass `null` to send no data
+        // Otherwise, F# compiler can't resolve the overload
+        return! Fetch.delete(url, null)
     }
 ```
 

diff --git a/nacara.js b/nacara.js
@@ -10,7 +10,7 @@ module.exports = {
     editUrl : "https://github.com/thoth-org/Thoth.Fetch/edit/master/docs",
     title: "Thoth.Fetch",
     debug: true,
-    version: "1.1.0",
+    version: "2.0.0",
     navbar: {
         showVersion: true,
         links: [