📝 Public API documentation (#6)

Author: abidon

.github/workflows/deploy_docc.yml

@@ -0,0 +1,43 @@
+name: Deploy DocC
+
+on:
+  push:
+    branches:
+      - "main"
+
+      
+permissions:
+  contents: write
+  
+# This allows a subsequently queued workflow run to interrupt previous runs
+concurrency:
+  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
+  cancel-in-progress: true
+  
+jobs:
+  build_docs:
+    runs-on: macos-latest
+    steps:
+      - uses: swift-actions/setup-swift@v1
+        with:
+          swift-version: "5.9"
+
+      - name: Checkout 🛎️
+        uses: actions/checkout@v3
+
+      - name: Build DocC
+        run: |
+          swift package resolve;
+          swift package --allow-writing-to-directory docs \
+            generate-documentation --target FluentData \
+            --disable-indexing \
+            --transform-for-static-hosting \
+            --hosting-base-path FluentData \
+            --output-path docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          destination_dir: docs

Sources/FluentData/Documentation.docc/Documentation.md

@@ -1,14 +1,17 @@
-# FluentData
+# Getting started with FluentData
 
 Add managed persistence to your SwiftUI app using the Fluent ORM.
 
 ## Overview
 
-Combining Fluent's proven ORM technology and Swift's modern concurrency features, FluentData enables you to add persistence to your app quickly, with minimal code. Inspired by SwiftData, FluentData gives additional control and features over data persistence in your SwiftUI app.
+Combining Fluent's proven ORM technology and Swift's modern concurrency features, FluentData enables you to add persistence to your app quickly, with minimal
+code. Inspired by SwiftData, FluentData gives additional control and features over data persistence in your SwiftUI app.
+
+Browsing the [Fluent](https://docs.vapor.codes/fluent/overview/) documentation will prove to be useful as well, since FluentData relies on this library.
 
 ## Topics
 
-### Base API
+### Core API
 
 - ``FluentDataContextKey``
 - ``FluentDataContext``

Sources/FluentData/Documentation.docc/theme-settings.json

@@ -0,0 +1,6 @@
+{
+    "meta": {
+        "title": "FluentData - Documentation"
+    },
+    "theme": {}
+}

Sources/FluentData/FluentDataContext.swift

@@ -196,10 +196,6 @@ fileprivate protocol DatabaseStateTracker: AnyObject {
     func onUpdate(_ model: AnyModel, on db: Database) async
 }
 
-public enum ReadOnlyDatabaseError: Error {
-    case invalidOperation
-}
-
 fileprivate struct ReadOnlyMiddleware: AnyModelMiddleware {
     func handle(_ event: FluentKit.ModelEvent, _ model: FluentKit.AnyModel, on db: FluentKit.Database, chainingTo next: FluentKit.AnyModelResponder) -> NIOCore.EventLoopFuture<Void> {
         return db.eventLoop.makeFailedFuture(ReadOnlyDatabaseError.invalidOperation)

Sources/FluentData/FluentDataContextKey.swift

@@ -1,30 +1,13 @@
 import Foundation
 
-/// Supported storage mediums for a context
-///
-/// ``memory`` won't persist data across two launches of your app. This can be quite useful during the development process.
-///
-/// ``file(_:)`` on the other hand, will persist data on disk using the SQLite format.
-///
-/// ``bundle(_:name:)`` provide a read-only database using the SQLite format from a bundle file.
-/// The file will be located in the "Application Support" folder of the currently running application.
-public enum FluentDataPersistence {
-    case memory
-    case file(_ name: String)
-    case bundle(_ bundle: Bundle, name: String)
-}
-
-public enum MigrationFailurePolicy {
-    case startFresh
-    case abort
-    case backupAndStartFresh(backupHandler: (URL) -> Void)
-}
-
 /// An unique identifier for a database context
 public protocol FluentDataContextKey {
+    /// If set, SQL queries will be logged. Defaults to `true` in DEBUG configuration, false otherwise.
     static var logQueries: Bool { get }
 
+    /// Specify FluentData's behaviour if one of the migrations fail. Defaults to ``MigrationFailurePolicy/abort``.
     static var migrationFailurePolicy: MigrationFailurePolicy { get }
+    
     /// The list of migrations to apply
     ///
     /// Migrations allows your data model to evolve with your app. Migrations are automatically applied in order when the database context is created.

Sources/FluentData/FluentDataContexts.swift

@@ -1,7 +1,7 @@
 import FluentKit
 import Foundation
 
-/// A registry of `FluentDataContext`
+/// A registry for ``FluentDataContext`` instances
 public enum FluentDataContexts {
     private static var contexts: [ObjectIdentifier: FluentDataContext] = [:]
     private static var defaultId: ObjectIdentifier?
@@ -20,6 +20,7 @@ public enum FluentDataContexts {
         }
     }
 
+    /// Returns the default context, if any. Default context can be specified in ``FluentDataContext``'s initializer.
     public static var `default`: FluentDataContext? {
         guard let defaultId else { return nil }
         return contexts[defaultId]

Sources/FluentData/FluentDataPersistence.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+/// Specify the storage mediums of a context
+public enum FluentDataPersistence {
+    /// ``memory`` won't persist data across two launches of your app. This can be quite useful during the development process.
+    case memory
+    
+    /// ``file(_:)`` on the other hand, will persist data on disk using the SQLite format.
+    /// The file will be located in the "Application Support" folder of the currently running application.
+    case file(_ name: String)
+    
+    /// ``bundle(_:name:)`` provide a read-only database using the SQLite format from a bundle file.
+    case bundle(_ bundle: Bundle, name: String)
+}

Sources/FluentData/FluentQuery.swift

@@ -8,6 +8,8 @@ public class FluentQuery<Model: FluentKit.Model> {
     internal let queryBuilder: (QueryBuilder<Model>) -> QueryBuilder<Model>
     internal let queryId: UUID
     internal let subject = CurrentValueSubject<[Model], Error>([])
+    
+    /// Any subscriber to this publisher will receive new updates everytime FluentData determines the result has to be updated.
     public var publisher: AnyPublisher<[Model], Error> {
         subject
             .receive(on: DispatchQueue.main)
@@ -19,6 +21,10 @@ public class FluentQuery<Model: FluentKit.Model> {
             .eraseToAnyPublisher()
     }
 
+    /// Create a query object to fetch entries from the specified database context
+    /// - Parameters:
+    ///   - context: the context object
+    ///   - queryBuilder: optional, can be specified to customize the query, such as filters or the sort order
     public init(
         context: FluentDataContext,
         queryBuilder: @escaping (QueryBuilder<Model>) -> QueryBuilder<Model> = { $0 }
@@ -29,10 +35,10 @@ public class FluentQuery<Model: FluentKit.Model> {
         self.context.register(self)
     }
 
-    /// Create a query object to fetch entries from the specified database context
+    /// Create a query object to fetch entries from the specified database context key
     /// - Parameters:
     ///   - contextKey: the key which uniquely identify this context
-    ///   - queryBuilder: optional, can be specified to customize the query, such as the sort order
+    ///   - queryBuilder: optional, can be specified to customize the query, such as filters or the sort order
     public convenience init<TContextKey: FluentDataContextKey>(
         contextKey: TContextKey.Type,
         queryBuilder: @escaping (QueryBuilder<Model>) -> QueryBuilder<Model> = { $0 }
@@ -42,7 +48,7 @@ public class FluentQuery<Model: FluentKit.Model> {
 
     /// Create a query object to fetch entries from the default database context
     /// - Parameters:
-    ///   - queryBuilder: optional, can be specified to customize the query, such as the sort order
+    ///   - queryBuilder: optional, can be specified to customize the query, such as filters or the sort order
     public convenience init(
         queryBuilder: @escaping (QueryBuilder<Model>) -> QueryBuilder<Model> = { $0 }
     ) {

Sources/FluentData/MigrationFailurePolicy.swift

@@ -0,0 +1,16 @@
+import Foundation
+
+/// Recovery policy FluentData should adopt when a migration fails to execute
+///
+/// When using ``startFresh`` or ``backupAndStartFresh(backupHandler:)``, the process will crash if a new database cannot be created (similar to ``abort``)
+public enum MigrationFailurePolicy {
+    /// ``startFresh`` will wipe the database content and recreate a new database. This is not recommended in production as it brings data losses
+    case startFresh
+    
+    /// ``abort`` the process will crash voluntarily. Reasons why the migration failed to execute will be available in the logs.
+    case abort
+    
+    /// ``backupAndStartFresh(backupHandler:)`` will call the speccified closure with the URL to a copy of the database file which failed to migrate.
+    /// After the backup handler returns, the behaviour will be equivalent to ``startFresh``.
+    case backupAndStartFresh(backupHandler: (URL) -> Void)
+}

Sources/FluentData/ReadOnlyDatabaseError.swift

@@ -0,0 +1,5 @@
+/// Errors occuring while working with read-only databases
+public enum ReadOnlyDatabaseError: Error {
+    /// Thrown when trying to alter a read-only database
+    case invalidOperation
+}

Sources/FluentData/Utils/FieldKey+Extensions.swift

@@ -1,4 +1,7 @@
 public extension FieldKey {
+    /// Easily generate the complete field key for a group field
+    /// - Parameter field: Field key of inner field
+    /// - Returns: A new field key matching Fluent's expectations
     func group(field: FieldKey) -> FieldKey {
         return FieldKey(stringLiteral: "\(description)_\(field.description)")
     }

Sources/FluentData/WithFluentContext.swift

@@ -1,11 +1,15 @@
+/// Injects a FluentContext instance
 @propertyWrapper public struct WithFluentContext {
+    /// Injects the default context, if any, otherwise crashes the process
     public init() {
         guard let context = FluentDataContexts.default else {
             fatalError("FluentData has no default context")
         }
         self.context = context
     }
 
+    /// Injects the context matching the given key. Context needs to have been created beforehand.
+    /// - Parameter contextKey: the key which uniquely identify this context
     public init<K: FluentDataContextKey>(contextKey: K.Type) {
         self.context = FluentDataContexts[contextKey]
     }