KDoc: Events

Author: Avanatiker

common/src/main/kotlin/com/lambda/event/CallbackEvent.kt

@@ -1,3 +1,39 @@
 package com.lambda.event
 
+/**
+ * Represents an event that supports providing feedback after being posted to the [EventFlow].
+ *
+ * A [CallbackEvent] can be modified and listened to only from synchronous listeners ([EventFlow.syncListeners]).
+ * This allows the event to provide feedback after its invocation.
+ *
+ * Implement this interface when you need an event to return data back to the caller after being processed by the listeners.
+ *
+ * Usage:
+ * ```kotlin
+ * class MyCallbackEvent : CallbackEvent {
+ *     var result: ResultType? = null
+ * }
+ *
+ * object MyListener {
+ *    init {
+ *        // will be executed on the game thread synchronously
+ *        listener<MyCallbackEvent> { event ->
+ *            // will be readable after the event is posted
+ *            event.result = processEvent(event)
+ *            // ...
+ *        }
+ *
+ *        // will be executed on a dedicated thread asynchronously
+ *        concurrentListener<MyCallbackEvent> { event ->
+ *             // will not be readable after the event is posted as it takes time to execute
+ *             event.result = processEvent(event)
+ *        }
+ *    }
+ * }
+ *
+ * val event = MyCallbackEvent()
+ * EventFlow.post(event)
+ * val result = event.result
+ * ```
+ */
 interface CallbackEvent : Event

common/src/main/kotlin/com/lambda/event/Event.kt

@@ -1,3 +1,26 @@
 package com.lambda.event
 
+/**
+ * The base interface for all [Event]s in the system.
+ *
+ * An [Event] represents a state or condition that can be listened for and acted upon.
+ * It serves as a communication mechanism between different parts of an application.
+ *
+ * Subclasses of [Event] should encapsulate relevant information about the event's context and state.
+ *
+ * Implementations of this interface can be posted to the [EventFlow] for processing by registered listeners.
+ *
+ * Usage:
+ * ```kotlin
+ * class MyEvent(val message: String) : Event
+ *
+ * object MyListener {
+ *     init {
+ *         listener<MyEvent> { event -> println(event.message) }
+ *     }
+ * }
+ *
+ * EventFlow.post(MyEvent("Hello, world!"))
+ * ```
+ */
 interface Event

common/src/main/kotlin/com/lambda/event/events/PacketEvent.kt

@@ -38,3 +38,5 @@ abstract class PacketEvent : Event {
     abstract class Receive : PacketEvent() {
         class Pre(val packet: Packet<*>) : Receive(), ICancellable by Cancellable()
         class Post(val packet: Packet<*>) : Receive()
+    }
+}