Add usage documentation to readme (#12)

Author: JZDesign

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+# Title/IssueLink
+
+## Summary
+
+Please summarize the change that was made and why it was made.
+
+
+#### Characteristics
+
+- [ ] Feature completed
+- [ ] Dark code
+
+
+#### Tests
+
+- [ ] Tests are included in this PR
+- [ ] Tests were not included in this PR because ____
+
+
+#### Build/Tests
+
+- [ ] Builds and runs
+- [ ] Unit tests pass

README.md

@@ -1,5 +1,5 @@
 # HTTPEngine
-![Swift](https://github.com/JZDesign/HTTPEngine/workflows/Swift/badge.svg) [![SPM compatible](https://img.shields.io/badge/SPM-compatible-e66f20.svg?style=flat)](https://github.com/apple/swift-package-manager) [![Docs](https://img.shields.io/badge/Jazzy-Documentation-634fb3.svg?style=flat)](https://jzdesign.github.io/HTTPEngine/) 
+![Swift](https://github.com/JZDesign/HTTPEngine/workflows/Swift/badge.svg) [![SPM compatible](https://img.shields.io/badge/SPM-Compatible-e66f20.svg?style=flat)](https://github.com/apple/swift-package-manager) [![Docs](https://img.shields.io/badge/Jazzy-Documentation-634fb3.svg?style=flat)](https://jzdesign.github.io/HTTPEngine/) [![License](https://img.shields.io/badge/License-MIT-335577.svg?style=flat)](https://github.com/JZDesign/HTTPEngine/blob/master/LICENSE) 
 
 A convenience wrapper around Swift's Combine and URLSession to make `URLRequests`
 
@@ -13,3 +13,64 @@ dependencies: [
 ## [View Documentation](https://jzdesign.github.io/HTTPEngine/)
 
 Documentation generated by [Jazzy](https://github.com/realm/jazzy).
+
+
+## Usage
+### Get and decode
+```swift
+struct Recipes: Codable {
+    let id: String
+    let imageURLs: [String]
+    let title: String
+    let ingredients: [Ingredient]
+    let steps: [Step]
+}
+
+let engine = HTTPEngine()
+
+engine
+    .get([Recipes].self, url: "https://my-recipes.com/baby-back-ribs")
+    .assertNoFailure() // don't do this
+    .sink { recipes in
+}
+
+```
+
+### Post with encode and decode
+
+```swift
+struct NewUser: Codable {
+    let userName, email, password: String
+}
+
+struct NewUserResponse: Codable {
+    let id, accessToken, scope: String
+}
+
+let newUser = NewUser(userName: "Dudemus", email: "[email protected]", password: "This_R3@LLy_5h0uld_b3_encrypt3d")
+let engine = HTTPEngine()
+
+engine
+    .post(NewUserResponse.self, url: "https://auth.somedomain.com", body: newUser, validator: { $0 == 202 })
+    .catch {
+        // handle non 202 response or other errors
+    }
+    .assign(to: \.user, on: UserStore)
+
+```
+
+### Standard Requests
+
+```swift 
+let engine = HTTPEngine()
+
+engine
+    .makeRequest(method: .delete, url: "https://not-google.com/", body: data, header: headers, validator: { $0 == 204 })
+    .catch {
+        // handle non 204 response or other errors
+    }
+    .sink { data in
+        // handle response data
+    }
+
+```

Sources/HTTPEngine/Errors.swift

@@ -37,6 +37,7 @@ public struct Errors {
         /// - Returns: Error?
         ///
         /// ```swift
+        /// code ~= 200...299 -> nil // Success!
         /// code ~= 300...399 -> Errors.Response.redirect(statusCode)
         /// code ~= 400 -> Errors.Response.ClientError.badRequest_400
         /// code ~= 401 -> Errors.Response.ClientError.invalidCredentials_401

Sources/HTTPEngine/Utilities.swift

@@ -39,6 +39,15 @@ infix operator ??? : TernaryPrecedence
 ///   - right: Error
 /// - Throws: The error from the right
 /// - Returns: The unwrapped optional from the left
+///
+/// ```swift
+///     var x: Int? = nil
+///     let y = try x ??? SomeError() // Throws some Error
+///
+///     var value: Int? = 1
+///     let z = try value ??? SomeError() // unwraps value
+/// ```
+///
 public func ???<T>(_ left: Optional<T>, right: Error) throws -> T {
     guard let value = left else { throw right }
     return value

Tests/HTTPEngineTests/HTTPEngineTests.swift

@@ -72,7 +72,7 @@ final class HTTPEngineTests: XCTestCase {
         }
 
         HTTPEngine()
-            .makeRequest(method: .get, url: "https://google.com", validator:  { $0 == 202 })
+            .makeRequest(method: .get, url: "https://google.com", validator: { $0 == 202 })
             .assertError(test: self) {
                 switch $0 {
                 case Errors.Response.unexpectedStatusCode(let response):