Merge pull request #5 from futuredapp/feature/documentation

Add basic documentation and LICENSE

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Futured apps s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Package@swift-5.5.swift

@@ -0,0 +1,29 @@
+// swift-tools-version:5.5
+// Required for generation of DocC table of contents.
+import PackageDescription
+
+let package = Package(
+    name: "FuturedKit",
+    platforms: [
+        .iOS(.v13),
+        .macOS(.v10_15),
+        .watchOS(.v6),
+        .tvOS(.v13)
+    ],
+    products: [
+        .library(
+            name: "FuturedKit",
+            targets: ["FuturedKit"]
+        )
+    ],
+    targets: [
+        .target(
+            name: "FuturedKit",
+            dependencies: []
+        ),
+        .testTarget(
+            name: "FuturedKitTests",
+            dependencies: ["FuturedKit"]
+        )
+    ]
+)

README.md

@@ -1,3 +1,22 @@
 # FuturedKit
 
-A description of this package.
+SwiftUI state management tools, resources and views used by Futured.
+
+## Features
+
+- State management
+  - `Resource` modelling states for asynchronously loaded data
+    including errors, loading and refreshing.
+- Views
+  - `AnyShape` type-erased view for cases where you need to change the shape
+    easily by using ternary operator.
+
+## Contributions
+
+All contributions are welcome.
+
+Current maintainer and main contributor is [Matěj Kašpar Jirásek](https://github.com/mkj-is), <[email protected]>.
+
+## License
+
+FuturedKit is available under the MIT license. See the [LICENSE file](LICENSE) for more information.

Sources/FuturedKit/AnyShape.swift

@@ -1,12 +1,34 @@
 import SwiftUI
 
+/// A type-erased shape.
+///
+/// ## Overview
+///
+/// An `AnyShape` allows changing the type of shape used in a given view
+/// hierarchy. You can use it when different shapes are presented in the same
+/// place but using `AnyView` is too broad since it is not possible to apply
+/// `Shape` related modifiers.
+///
+/// ```swift
+/// var body: some Shape {
+///     (isCapsule ? AnyShape(Capsule()) : AnyShape(Rectangle()))
+///         .stroke()
+/// }
+/// ```
 public struct AnyShape: Shape {
     private let path: (CGRect) -> Path
 
+    /// Create an instance that type-erases a shape.
+    /// - Parameter shape: Concrete type conforming to `Shape`.
     public init<S>(_ shape: S) where S: Shape {
         self.path = shape.path
     }
 
+    /// Describes this shape as a path within a rectangular frame of reference.
+    ///
+    /// - Parameter rect: The frame of reference for describing this shape.
+    ///
+    /// - Returns: A path that describes this shape.
     public func path(in rect: CGRect) -> Path {
         self.path(rect)
     }

Sources/FuturedKit/Documentation.docc/Documentation.md

@@ -0,0 +1,13 @@
+# ``FuturedKit``
+
+SwiftUI state management tools, resources and views used by Futured.
+
+## Topics
+
+### State management
+
+- ``Resource``
+
+### Views
+
+- ``AnyShape``

Sources/FuturedKit/Publisher+Resource.swift

@@ -1,6 +1,9 @@
 import Combine
 
 extension Publisher {
+    /// Transforms all elements and failures to ``Resource``.
+    /// - Returns: Upstream publisher wrapped using map and catch operators
+    ///   with ``Resource`` as output type and `Never` as failure. 
     @inlinable
     public func resource() -> Publishers.Catch<
         Publishers.Map<Self, Resource<Output, Failure>>, Just<Resource<Output, Failure>>

Sources/FuturedKit/Resource.swift

@@ -1,34 +1,70 @@
+/// Represents asynchronously loaded data and their state
+/// including loading, errors and even refreshing.
+///
+/// ## Overview
+///
+/// States are not exclusive, you can even have error and content
+/// if its required to represent error which happened during
+/// refreshing.
+///
+/// This is ideal for modelling state for remotely loaded resource
+/// in any app.
 public struct Resource<Content, Failure: Error> {
+    /// Content if it was loaded.
     public var content: Content?
+    /// Flag representing if the resource is currently loading.
     public var isLoading: Bool
+    /// Optional strongly-typed error which occured during the load or refresh.
     public var error: Failure?
 
+    /// Created a new resource.
+    /// - Parameters:
+    ///   - content: Optional content. Default value is `nil`.
+    ///   - isLoading: Loading flag. Default value is `false`.
+    ///   - error: Optional error. Default value is `nil`.
     public init(content: Content? = nil, isLoading: Bool = false, error: Failure? = nil) {
         self.content = content
         self.isLoading = isLoading
         self.error = error
     }
 
+    /// Created a new resource with pre-loaded content.
+    ///
+    /// ## Discussion
+    ///
+    /// Loading flag will be set to false and error will be set to `nil`.
     public init(content: Content) {
         self.content = content
         self.isLoading = false
         self.error = nil
     }
 
+    /// Created a new resource with error.
+    ///
+    /// ## Discussion
+    ///
+    /// Loading flag will be set to false and content will be set to `nil`.
     public init(error: Failure) {
         self.content = nil
         self.isLoading = false
         self.error = error
     }
 
+    /// Read-only flag representing if the content is refreshing.
+    ///
+    /// ## Discussion
+    ///
+    /// The flag is set to true when the resource is loading and has some content.
     public var isRefreshing: Bool {
         isLoading && hasContent
     }
 
+    /// Read-only flag representing if the content is present.
     public var hasContent: Bool {
         content != nil
     }
 
+    /// Read-only flag representing if some error occured.
     public var hasFailed: Bool {
         error != nil
     }