Merge pull request #30 from k-kohey/add_code_document

Add code document

Author: k-kohey

Sources/Parchment/AnyLoggable.swift

@@ -36,6 +36,10 @@ public struct AnyLoggable: Loggable {
         self.parameters = parameters
     }
 
+    /// Recursively searches for the instance  `base` used to initialize this type and checks
+    /// for the existence of an instance of the type passed as an argument.
+    ///
+    /// This is useful for checking for lost type information, since type information is lost in conversions using `Parchment.Mutation`.
     @AnyLoggableActor
     public func isBased<T: Loggable>(_ type: T.Type) -> Bool {
         if findCache[id]?["\(T.self)"] == true {

Sources/Parchment/BufferFlowController.swift

@@ -6,7 +6,28 @@
 //
 import Foundation
 
+/// Helps in managing the flow of logs between LoggerBundler and LogBuffer.
+/// It provides functions for input and output operations on logs in a LogBuffer.
 public protocol BufferFlowController: Sendable {
+    /// Saves the given Payload to LogBuffer.
+    ///
+    /// Depending on the LogBuffer implementation, it may be better to store a certain number of payloads at once.
+    /// In such cases, this function can delay saving until a certain number of payloads are stored.
+    ///
+    /// - Parameters:
+    ///   - _: The array of Payload objects to be saved.
+    ///   - buffer: The LogBuffer where the Payload objects will be saved.
     func input<T: LogBuffer>(_: [Payload], with buffer: T) async throws
+
+    /// Asynchronously read Payload from LogBuffer based on certain conditions
+    ///
+    /// Read an arbitrary number of Logs from Buffer at an arbitrary timing
+    /// using polling, observer patterns, etc., and send them to AsyncStream.
+    ///
+    /// Note that if no events flow into the return value AsyncStream,
+    /// the LoggerBundler will not be able to retrieve the buffered log from the LogBuffer.
+    ///
+    /// - Parameter _: The LogBuffer from which the Payload objects will be loaded.
+    /// - Returns: Stream for LoggerBundler to subscribe and send Log to LoggerComponent
     func output<T: LogBuffer>(with: T) async -> AsyncThrowingStream<[Payload], Error>
 }

Sources/Parchment/Configuration.swift

@@ -0,0 +1,23 @@
+//
+//  LogBuffer.swift
+//
+//
+//  Created by k-kohey on 2021/12/29.
+//
+
+import Foundation
+
+/// `LogBuffer` represents a protocol for managing Payload objects.
+///
+/// By implementing this Protocol, Log can be buffered to an arbitrary location such as a text file or database.
+public protocol LogBuffer: Sendable {
+    func enqueue(_ event: [Payload]) async throws
+    func dequeue(limit: Int?) async throws -> [Payload]
+    func count() async throws -> Int
+}
+
+public extension LogBuffer {
+    func load() async throws -> [Payload] {
+        try await dequeue(limit: nil)
+    }
+}

Sources/Parchment/LogBuffer.swift

@@ -11,16 +11,13 @@ public final actor LoggerBundler {
     private let buffer: LogBuffer
     private let bufferFlowController: BufferFlowController
 
-    public var configMap: [LoggerComponentID: Configuration] = [:]
     private(set) var transform: Transform
 
-    private var loggingTask: Task<Void, Never>?
-
     public init(
         components: [any LoggerComponent],
         buffer: some LogBuffer,
         bufferFlowController: some BufferFlowController,
-        mutations: [Mutation] = []
+        mutations: [any Mutation] = []
     ) {
         self.components = components
         self.buffer = buffer
@@ -33,7 +30,9 @@ public final actor LoggerBundler {
     }
 
     public func add(mutations: [Mutation]) {
-        transform = [transform, mutations.composed()].composed()
+        transform = [
+            transform, mutations.composed()
+        ].composed()
     }
 
     /// Sends a Log to the retained LoggerComponents.
@@ -90,6 +89,8 @@ public final actor LoggerBundler {
         }
     }
 
+    /// Dequeue Log from Buffer and start sending Log to LoggerComponent.
+    /// The number and timing of Log dequeues are determined by BufferFlowController.
     @discardableResult
     public func startLogging() -> Task<Void, Error> {
         Task {
@@ -115,16 +116,34 @@ public final actor LoggerBundler {
 }
 
 public extension LoggerBundler {
+    /// Log sending timing
     enum LoggingPolicy: Sendable {
+        /// requires the log o be sent to LoggerComponent immediately without storing it in the buffer.
+        /// When this is specified, logs can be sent ignoring the waiting order of buffer.
         case immediately
         case bufferingFirst
     }
 
+    /// Scope of sending logs
+    ///
+    /// If specified as follows, Logs are sent only to the LoggerComponent
+    /// whose LoggerComponentID is defined as myLogger.
+    ///
+    ///      extension LoggerComponentID {
+    ///         static var myLogger: LoggerComponentID = { .init("myLogger") }
+    ///      }
+    ///
+    ///      await logger.send(
+    ///         event,
+    ///         with: .init(scope: .only(.myLogger))
+    ///      )
     enum LoggerScope: Sendable {
         case only([LoggerComponentID])
         case exclude([LoggerComponentID])
     }
 
+    ///  Settings on how logs are sent
+    ///  The default settings sends logs to all LoggerComponents after first storing them in a buffer
     struct LoggingOption: Sendable {
         let policy: LoggingPolicy
         let scope: LoggerScope?
@@ -139,16 +158,6 @@ public extension LoggerBundler {
     }
 }
 
-public extension LoggerBundler {
-    struct Configuration {
-        let allowBuffering: Bool
-
-        public init(allowBuffering: Bool) {
-            self.allowBuffering = allowBuffering
-        }
-    }
-}
-
 public extension LoggerBundler {
     func send(event: TrackingEvent, with option: LoggingOption = .init()) async {
         await send(event, with: option)

Sources/Parchment/LoggerBundler.swift

@@ -19,8 +19,17 @@ public protocol LoggerSendable: Sendable {
     var timestamp: Date { get }
 }
 
+/// Sending logs to your server or SDK such as Firebase.
 public protocol LoggerComponent: Sendable {
+
+    /// A unique identifier.
+    /// This definition allows the user to specify an id when sending logs.
     static var id: LoggerComponentID { get }
+
+    /// Sends an array of `LoggerSendable` objects asynchronously.
+    ///
+    /// - Parameter _: The array of `LoggerSendable` objects to send.
+    /// - Returns: A boolean indicating whether the operation was successful.
     func send(_: [any LoggerSendable]) async -> Bool
 }
 

Sources/Parchment/LoggerComponent.swift

@@ -9,8 +9,25 @@ import Foundation
 
 typealias Transform = @Sendable @AnyLoggableActor (Loggable, LoggerComponentID) -> AnyLoggable
 
+/// Transform a given log into another log.
+///
+/// If there are parameters that should be inserted for all logs, such as UserID and Timestamp,
+/// `Mutation` can be used to implement this.
+///
+/// The example below illustrates how to use `Mutation` to insert a UserID into the parameters of a log.
+/// By implementing it in this way, it saves the effort of inserting this into each individual log.
+///
+///     struct UserIDMutation: Mutation {
+///         let userID: ID
+///
+///         func transform(_ e: Loggable, id: LoggerComponentID) -> AnyLoggable {
+///             var e = AnyLoggable(e)
+///             e.parameters["userID"] = userID
+///             return e
+///         }
+///     }
 public protocol Mutation: Sendable {
-    @AnyLoggableActor 
+    @AnyLoggableActor
     func transform(_: any Loggable, id: LoggerComponentID) -> AnyLoggable
 }
 

Sources/Parchment/Mutation.swift

@@ -7,6 +7,12 @@
 
 import Foundation
 
+/// Logs changes to a value.
+///
+/// Mark the properties for which you wish to log changes as follows.
+///
+///     @Tracked(name: "age", with: logger) var age: Int
+///     @Tracked(name: "age", with: logger, scope: \.age) var state: State
 @propertyWrapper
 public struct Tracked<Value: Sendable, ScopeValue: Sendable> {
     private let logger: LoggerBundler

Sources/Parchment/Tracked.swift

@@ -36,6 +36,7 @@ private struct Impletion: ViewModifier {
 }
 
 public extension View {
+    /// Hook onAppear to send ImpletionEvent
     func track(
         screen name: String,
         with logger: LoggerBundler,

Sources/Parchment/TrackingEventBuffer.swift

@@ -34,7 +34,7 @@ public final class DefaultBufferFlowController: BufferFlowController, Sendable {
         _ events: [Payload], with buffer: T
     ) async throws {
         @Sendable @MainActor func save() async throws {
-            try await buffer.save(inputAccumulationPayloads)
+            try await buffer.enqueue(inputAccumulationPayloads)
             inputAccumulationPayloads = []
         }
 

Sources/Parchment/View+track.swift

@@ -41,7 +41,7 @@ public final actor SQLiteBuffer: LogBuffer {
         )
     }
 
-    public func save(_ e: [Payload]) throws {
+    public func enqueue(_ e: [Payload]) throws {
         try db.run(
             try events.insertMany(
                 e.map {
@@ -58,7 +58,7 @@ public final actor SQLiteBuffer: LogBuffer {
         )
     }
 
-    public func load(limit: Int?) throws -> [Payload] {
+    public func dequeue(limit: Int?) throws -> [Payload] {
         let target = events.order(Column.timestamp).limit(limit)
         let entities = try db.prepare(target)
             .map { $0[Column.event] }

Sources/ParchmentDefault/DefaultBufferFlowController.swift

@@ -13,11 +13,11 @@ import XCTest
 final class EventQueueMock: LogBuffer, @unchecked Sendable {
     private var records: [Payload] = []
 
-    func save(_ e: [Payload]) {
+    func enqueue(_ e: [Payload]) {
         records += e
     }
 
-    func load(limit: Int?) async throws -> [Parchment.Payload] {
+    func dequeue(limit: Int?) async throws -> [Parchment.Payload] {
         let count: Int
         if let limit {
             count = limit
@@ -115,7 +115,7 @@ class RegularlyPollingSchedulerTests: XCTestCase {
                 return
             }
         }
-        buffer.save([.init(destination: "hoge", event: event, timestamp: Date())])
+        buffer.enqueue([.init(destination: "hoge", event: event, timestamp: Date())])
 
         while outputEvent == nil {
             await Task.yield()

Sources/ParchmentDefault/SQLiteBuffer.swift

@@ -31,7 +31,7 @@ final class SQLiteBufferTests: XCTestCase {
             )
         ]
 
-        try await db.save(records)
+        try await db.enqueue(records)
         let results = try await db.load()
 
         XCTAssertEqual(
@@ -68,7 +68,7 @@ final class SQLiteBufferTests: XCTestCase {
         XCTAssertEqual(initalState, 0)
 
         do {
-            try await db.save(records)
+            try await db.enqueue(records)
             let result = try await db.count()
             XCTAssertEqual(result, 3)
         }
@@ -104,8 +104,8 @@ final class SQLiteBufferTests: XCTestCase {
             )
         ]
 
-        try await db.save(records)
-        let result = try await db.load(limit: 2)
+        try await db.enqueue(records)
+        let result = try await db.dequeue(limit: 2)
 
         let count = try await db.count()
         XCTAssertEqual(count, 1)

Tests/ParchmentDefaultTests/DefaultBufferFlowControllerTests.swift

@@ -35,11 +35,11 @@ final class LoggerB: LoggerComponent, @unchecked Sendable {
 final class EventQueueMock: LogBuffer, @unchecked Sendable {
     private var records: [Payload] = []
 
-    func save(_ e: [Payload]) {
+    func enqueue(_ e: [Payload]) {
         records += e
     }
 
-    func load(limit: Int?) async throws -> [Parchment.Payload] {
+    func dequeue(limit: Int?) async throws -> [Parchment.Payload] {
         let count: Int
         if let limit {
             count = limit
@@ -71,7 +71,7 @@ final class BufferedEventFlushStrategyMock: BufferFlowController, @unchecked Sen
     private var continuation: AsyncThrowingStream<[Payload], Error>.Continuation?
 
     func input<T: LogBuffer>(_ payloads: [Payload], with buffer: T) async throws {
-        try await buffer.save(payloads)
+        try await buffer.enqueue(payloads)
     }
 
     func output<T: LogBuffer>(with buffer: T) async -> AsyncThrowingStream<[Payload], Error> {