Doc Comment Improvements

preparing for a v1 release, so need to ensure the doc comments are solid.

Author: LK-Simon

Sources/EventDrivenSwift/Central/EventCentral.swift

@@ -12,7 +12,6 @@ import Foundation
 Singleton for the Central Event Handler.
  - Author: Simon J. Stuart
  - Version: 1.0.0
- to access the Central Event Handler.
  - Note: This is a Singleton!
  - Note: This is used when invoking the `queue` and `stack` methods of `Eventable`.
  */
@@ -26,6 +25,4 @@ final public class EventCentral: EventDispatcher {
     }
 
     override private init() {}
-    
-    
 }

Sources/EventDrivenSwift/EventDispatcher/EventDispatcher.swift

@@ -10,7 +10,13 @@ import Foundation
 import ThreadSafeSwift
 import Observable
 
-public class EventDispatcher: EventHandler, EventDispatchable {   
+/**
+ An implementation of `EventHandler` designed to Queue/Stack outbound events, and Dispatch them to all registered `listeners`
+ - Author: Simon J. Stuart
+ - Version: 1.0.0
+ - Note: While you can inherit from and even create instances of `EventDispatcher`, best practice would be to use `EventCentral.shared` as the central Event Dispatcher.
+ */
+open class EventDispatcher: EventHandler, EventDispatchable {
     struct ListenerContainer {
         weak var listener: (any EventReceivable)?
     }

Sources/EventDrivenSwift/EventHandler/EventHandler.swift

@@ -10,6 +10,12 @@ import Foundation
 import ThreadSafeSwift
 import Observable
 
+/**
+ Abstract Base Type for all `EventHandler` Thread Types.
+ - Author: Simon J. Stuart
+ - Version: 1.0.0
+ - Note: This is the Common Base Type for `EventDispatcher` and `EventReceiver` base types
+ */
 open class EventHandler: ObservableThread, EventHandlable {
     /**
     A Map of `EventPriority` against an Array of `Eventable` in that corresponding Queue
@@ -37,25 +43,26 @@ open class EventHandler: ObservableThread, EventHandlable {
             var stackCount: Int = 0
             var queueCount: Int = 0
 
-            var snapStacks = [EventPriority:[any Eventable]]()
-            var snapQueues = [EventPriority:[any Eventable]]()
+            var snapStacks = [EventPriority:[any Eventable]]() // Snapshot of the current Stacks
+            var snapQueues = [EventPriority:[any Eventable]]() // Snapshot of hte current Queues
 
-            _stacks.withLock { stacks in
-                snapStacks = stacks
-            }
-            _queues.withLock { queues in
-                snapQueues = queues
-            }
+            _stacks.withLock { stacks in // With the Lock
+                snapStacks = stacks // Grab a Snapshot
+            } // Lock releases
 
-            for stack in snapStacks.values {
-                stackCount += stack.count
+            _queues.withLock { queues in // With the Lock
+                snapQueues = queues // Grab a Snapshot
+            } // Lock releases
+            
+            for stack in snapStacks.values { // Iterate Stacks
+                stackCount += stack.count // Increment Count
             }
 
-            for queue in snapQueues.values {
-                queueCount += queue.count
+            for queue in snapQueues.values { // Iterate Queues
+                queueCount += queue.count // Increment Count
             }
 
-            return stackCount + queueCount
+            return stackCount + queueCount // Return the sum of Stack and Queue counts (total Event Count)
         }
     }
 
@@ -146,6 +153,11 @@ open class EventHandler: ObservableThread, EventHandlable {
         }
     }
 
+    /**
+     Simple Macro to process first the Stacks, then the Queues
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     */
     internal func processAllEvents() {
         processEventStacks() // we process Stacks first
         processEventQueues() // we process Queues next

Sources/EventDrivenSwift/EventReceiver/EventReceiver.swift

@@ -10,7 +10,13 @@ import Foundation
 import ThreadSafeSwift
 import Observable
 
-public class EventReceiver: EventHandler, EventReceivable {
+/**
+ Abstract Base Type for all `EventRecevier` Thread Types.
+ - Author: Simon J. Stuart
+ - Version: 1.0.0
+ - Note: Inherit from this to implement a discrete unit of code designed specifically to operate upon specific `Eventable` types containing information useful to its operation(s)
+ */
+open class EventReceiver: EventHandler, EventReceivable {
     /**
      Convienience `typealias` used for Event Callbacks
      - Author: Simon J. Stuart
@@ -33,8 +39,6 @@ public class EventReceiver: EventHandler, EventReceivable {
      */
     @ThreadSafeSemaphore private var eventCallbacks = [String:EventCallback]() //TODO: Make this a Revolving Door collection!
 
-//    @ThreadSafeSemaphore private var typedEventCallbacks = [String:Any]() //TODO: Find an implementation that works for strong-typed Event Callbacks (P.S. limitations of Swift Generics are very annoying!)
-    
     /**
      Invoke the appropriate Callback for the given Event
      - Author: Simon J. Stuart
@@ -72,24 +76,21 @@ public class EventReceiver: EventHandler, EventReceivable {
         EventCentral.shared.addListener(self, forEventType: forEventType)
     }
 
+    /**
+     Performs a Transparent Type Test, Type Cast, and Method Call via the `callback` Closure.
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     - Parameters:
+        - callback: The code (Closure or Callback Method) to execute for the given `forEvent`, typed generically using `TEvent`
+        - forEvent: The instance of the `Eventable` type to be processed
+        - priority: The `EventPriority` with which the `forEvent` was dispatched
+     */
     internal func callTypedEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEvent: Eventable, priority: EventPriority) {
         if let typedEvent = forEvent as? TEvent {
             callback(typedEvent, priority)
         }
     }
 
-    //TODO: Find an implementation that works for strong-typed Event Callbacks (P.S. limitations of Swift Generics are very annoying!)
-//    internal func addEventCallback<TEvent: Eventable>(_ callback: @escaping TypedEventCallback<TEvent>, forEventType: Eventable.Type) {
-//        let eventTypeName = String(reflecting: forEventType)
-//
-//        _typedEventCallbacks.withLock { typedEventCallbacks in
-//            typedEventCallbacks[eventTypeName] = callback
-//        }
-//
-//        /// We automatically register the Listener with the Central Event Dispatcher
-//        EventCentral.shared.addListener(self, forEventType: forEventType)
-//    }
-    
     /**
      Removes an Event Callback for the given `Eventable` Type
      - Author: Simon J. Stuart
@@ -114,6 +115,11 @@ public class EventReceiver: EventHandler, EventReceivable {
         // No default implementation
     }
 
+    /**
+     Initializes an `EventReciever` decendant and invokes `registerEventListeners()` to register your Event Listeners within your `EventReceiver` type.
+     - Author: Simon J. Stuart
+     - Version: 1.0.0
+     */
     override init() {
         super.init()
         registerEventListeners()