Merge pull request #89 from futuredapp/feature/docc-documentation

DocC documentation

FTAPIKit.podspec

@@ -15,6 +15,7 @@ Pod::Spec.new do |s|
 
   s.source                      = { git: "https://github.com/futuredapp/FTAPIKit.git", tag: s.version.to_s }
   s.source_files                = "Sources/FTAPIKit/**/*"
+  s.exclude_files               = "Sources/FTAPIKit/Documentation.docc/**/*"
 
   s.frameworks                  = ["Foundation", "CoreServices"]
   s.weak_frameworks             = ["Combine"]

Gemfile.lock

@@ -1,23 +1,25 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.3)
-    activesupport (5.2.5)
+    CFPropertyList (3.0.4)
+      rexml
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
     addressable (2.8.0)
       public_suffix (>= 2.0.2, < 5.0)
     algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
     atomos (0.1.3)
     claide (1.0.3)
-    cocoapods (1.10.1)
-      addressable (~> 2.6)
+    cocoapods (1.11.2)
+      addressable (~> 2.8)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.10.1)
+      cocoapods-core (= 1.11.2)
       cocoapods-deintegrate (>= 1.0.3, < 2.0)
       cocoapods-downloader (>= 1.4.0, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
@@ -28,60 +30,62 @@ GEM
       escape (~> 0.0.4)
       fourflusher (>= 2.3.0, < 3.0)
       gh_inspector (~> 1.0)
-      molinillo (~> 0.6.6)
+      molinillo (~> 0.8.0)
       nap (~> 1.0)
-      ruby-macho (~> 1.4)
-      xcodeproj (>= 1.19.0, < 2.0)
-    cocoapods-core (1.10.1)
-      activesupport (> 5.0, < 6)
-      addressable (~> 2.6)
+      ruby-macho (>= 1.0, < 3.0)
+      xcodeproj (>= 1.21.0, < 2.0)
+    cocoapods-core (1.11.2)
+      activesupport (>= 5.0, < 7)
+      addressable (~> 2.8)
       algoliasearch (~> 1.0)
       concurrent-ruby (~> 1.1)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
       netrc (~> 0.11)
-      public_suffix
+      public_suffix (~> 4.0)
       typhoeus (~> 1.0)
-    cocoapods-deintegrate (1.0.4)
-    cocoapods-downloader (1.4.0)
+    cocoapods-deintegrate (1.0.5)
+    cocoapods-downloader (1.5.1)
     cocoapods-plugins (1.0.0)
       nap
-    cocoapods-search (1.0.0)
-    cocoapods-trunk (1.5.0)
+    cocoapods-search (1.0.1)
+    cocoapods-trunk (1.6.0)
       nap (>= 0.8, < 2.0)
       netrc (~> 0.11)
     cocoapods-try (1.2.0)
     colored2 (3.1.2)
-    concurrent-ruby (1.1.8)
+    concurrent-ruby (1.1.9)
     escape (0.0.4)
-    ethon (0.14.0)
+    ethon (0.15.0)
       ffi (>= 1.15.0)
-    ffi (1.15.0)
+    ffi (1.15.4)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
     httpclient (2.8.3)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    json (2.5.1)
+    json (2.6.0)
     minitest (5.14.4)
-    molinillo (0.6.6)
+    molinillo (0.8.0)
     nanaimo (0.3.0)
     nap (1.1.0)
     netrc (0.11.0)
     public_suffix (4.0.6)
-    ruby-macho (1.4.0)
-    thread_safe (0.3.6)
+    rexml (3.2.5)
+    ruby-macho (2.5.1)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    tzinfo (1.2.9)
-      thread_safe (~> 0.1)
-    xcodeproj (1.19.0)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    xcodeproj (1.21.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
       claide (>= 1.0.2, < 2.0)
       colored2 (~> 3.1)
       nanaimo (~> 0.3.0)
+      rexml (~> 3.2.4)
+    zeitwerk (2.5.1)
 
 PLATFORMS
   ruby
@@ -90,4 +94,4 @@ DEPENDENCIES
   cocoapods (~> 1.10)
 
 BUNDLED WITH
-   2.2.16
+   2.2.29

Package.swift

@@ -13,9 +13,11 @@ let package = Package(
     targets: [
         .target(
             name: "FTAPIKit",
-            dependencies: []),
+            dependencies: []
+        ),
         .testTarget(
             name: "FTAPIKitTests",
-            dependencies: ["FTAPIKit"])
+            dependencies: ["FTAPIKit"]
+        )
     ]
 )

Package@swift-5.5.swift

@@ -0,0 +1,22 @@
+// swift-tools-version:5.5
+// This manifest is needed to properly generate DocC documentation.
+
+import PackageDescription
+
+let package = Package(
+    name: "FTAPIKit",
+    platforms: [.iOS(.v12), .macOS(.v10_10), .tvOS(.v12), .watchOS(.v5)],
+    products: [
+        .library(
+            name: "FTAPIKit",
+            targets: ["FTAPIKit"])
+    ],
+    targets: [
+        .target(
+            name: "FTAPIKit",
+            dependencies: []),
+        .testTarget(
+            name: "FTAPIKitTests",
+            dependencies: ["FTAPIKit"])
+    ]
+)

README.md

@@ -1,4 +1,4 @@
-<img align="right" alt="FTAPIKit logo" src="Documentation/FTAPIKit.svg">
+<img align="right" alt="FTAPIKit logo" src="Sources/FTAPIKit/Documentation.docc/Resources/FTAPIKit.svg">
 
 # FTAPIKit
 
@@ -45,7 +45,7 @@ If some advanced features are required then we recommend implementing API client
 This client should encapsulate logic which is not provided by this framework
 (like signing authorized endpoints or conforming to `URLSessionDelegate`).
 
-![Architecture](Documentation/Architecture.svg)
+![Architecture](Sources/FTAPIKit/Documentation.docc/Resources/Architecture.svg)
 
 This package contains predefined `Endpoint` protocols.
 Use cases like multipart upload, automatic encoding/decoding
@@ -60,7 +60,7 @@ are separated in various protocols for convenience.
 - `RequestEndpoint` has encodable request which is encoded using encoding
   of the `Server` instance.
 
-![Endpoint types](Documentation/Endpoints.svg)
+![Endpoint types](Sources/FTAPIKit/Documentation.docc/Resources/Endpoints.svg)
 
 ## Usage
 

Sources/FTAPIKit/APIError+Standard.swift

@@ -4,13 +4,15 @@ import Foundation
 import FoundationNetworking
 #endif
 
-/// Standard API error returned in `APIResult` when no custom error
-/// was parsed in the `APIAdapter` first and the response from server
+/// Standard API error returned when no custom error
+/// was parsed and the response from server
 /// was invalid.
 public enum APIErrorStandard: APIError {
-    /// Error raised by URLSession.
+    /// Error returned by URL loading APIs.
     case connection(URLError)
+    /// An error that occurs during the encoding of a value.
     case encoding(EncodingError)
+    /// An error that occurs during the decoding of a value.
     case decoding(DecodingError)
     /// Status code error when the response status code
     /// is larger or equal to 500 and less than 600.

Sources/FTAPIKit/APIError.swift

@@ -4,14 +4,14 @@ import Foundation
 import FoundationNetworking
 #endif
 
-/// Error protocol used in types conforming to `URLServer` protocol. Default implementation called `APIErrorStandard`
-/// is provided. A type conforming to `APIError` protocol can be provided to `URLServer`
+/// Error protocol used in types conforming to ``URLServer`` protocol. Default implementation called ``APIErrorStandard``
+/// is provided. A type conforming to ``APIError`` protocol can be provided to ``URLServer``
 /// to use custom error handling.
 ///
 /// - Note: Since this type is specific to the standard implementation, it works with Foundation `URLSession`
 /// network API.
 public protocol APIError: Error {
-    /// Standard implementation of `APIError`
+    /// Standard implementation of ``APIError``
     typealias Standard = APIErrorStandard
 
     /// Creates instance if arguments do not represent a valid server response.

Sources/FTAPIKit/CaracterSet+UrlQuery.swift

@@ -5,6 +5,9 @@ extension CharacterSet {
     private static let urlSubDelimiters: CharacterSet = ["!", "$", "&", "'", "(", ")", "*", "+", ",", ";", "="]
     private static let urlDelimiters = CharacterSet.urlGeneralDelimiters.union(.urlSubDelimiters)
 
-    /// https://tools.ietf.org/html/rfc3986#section-2.2
+    /// All characters allowed in URL query name or value.
+    ///
+    /// > Note: The list of characters is derived from
+    /// > [RFC-3986 Section 2.2](https://tools.ietf.org/html/rfc3986#section-2.2).
     static let urlQueryNameValueAllowed = CharacterSet.urlQueryAllowed.subtracting(.urlDelimiters)
 }

Sources/FTAPIKit/Coding.swift

@@ -6,8 +6,6 @@ import FoundationNetworking
 
 /// `Encoding` represents Swift encoders and provides network-specific features, such as configuring
 /// the request with correct headers.
-///
-/// - Note: A standard implementation is provided in the form of `JSONEncoding`
 public protocol Encoding {
 
     /// Encodes the argument
@@ -19,13 +17,14 @@ public protocol Decoding {
     func decode<T: Decodable>(data: Data) throws -> T
 }
 
-/// Protocol extending types conforming to encoding
+/// Protocol extending encoding with ability to configure `URLRequest`. Used when encoding endpoints in ``URLServer`` calls.
 public protocol URLRequestEncoding: Encoding {
-    /// Can configure the request with proper headers such as `Content-Type`.
+    /// Allows modification of `URLRequest`. Enables things like adding `Content-Type` header etc.
+    /// - Parameter request: Request which can be modified.
     func configure(request: inout URLRequest) throws
 }
 
-/// Type-erased JSON encoder for use with types conforming to `Server` protocol.
+/// Type-erased JSON encoder for use with types conforming to ``Server`` protocol.
 public struct JSONEncoding: URLRequestEncoding {
     private let encoder: JSONEncoder
 
@@ -52,7 +51,7 @@ public struct JSONEncoding: URLRequestEncoding {
     }
 }
 
-/// Type-erased JSON decoder for use with types conforming to `Server` protocol.
+/// Type-erased JSON decoder for use with types conforming to ``Server`` protocol.
 public struct JSONDecoding: Decoding {
     private let decoder: JSONDecoder
 

Sources/FTAPIKit/Documentation.docc/Documentation.md

@@ -0,0 +1,49 @@
+# ``FTAPIKit``
+
+Declarative, generic and protocol-oriented REST API framework using `URLSession` and `Codable`
+
+## Overview
+
+Declarative and generic REST API framework using `Codable`.
+With standard implementation using `URLSesssion` and JSON encoder/decoder.
+Easily extensible for your asynchronous framework or networking stack.
+
+![Tree with a API Client root element. Its branches are servers. Each server branch has some endpoint branches.](Architecture)
+
+## Topics
+
+### Server
+
+- ``Server``
+- ``URLServer``
+
+### Endpoint
+
+- ``Endpoint``
+- ``DataEndpoint``
+- ``UploadEndpoint``
+- ``MultipartEndpoint``
+- ``URLEncodedEndpoint``
+- ``EncodableEndpoint``
+- ``ResponseEndpoint``
+- ``RequestEndpoint``
+- ``RequestResponseEndpoint``
+
+### Endpoint configuration
+
+- ``HTTPMethod``
+- ``URLQuery``
+- ``MultipartBodyPart``
+
+### Encoding and decoding
+
+- ``Encoding``
+- ``JSONEncoding``
+- ``Decoding``
+- ``JSONDecoding``
+- ``URLRequestEncoding``
+
+### Error handling
+
+- ``APIError``
+- ``APIErrorStandard``