Lots of new KDocs

Author: Avanatiker

common/src/main/kotlin/com/lambda/context/AbstractContext.kt

@@ -6,6 +6,15 @@ import net.minecraft.client.network.ClientPlayerEntity
 import net.minecraft.client.network.ClientPlayerInteractionManager
 import net.minecraft.client.world.ClientWorld
 
+/**
+ * Representing an abstract context in the [MinecraftClient].
+ *
+ * @property mc The Minecraft client instance.
+ * @property world The world in which the player is currently located, or `null` if the world is not available.
+ * @property player The player entity, or `null` if the player is not available.
+ * @property interaction The interaction manager for the player, or `null` if the interaction manager is not available.
+ * @property connection The network handler for the player, or `null` if the network handler is not available.
+ */
 abstract class AbstractContext {
     val mc: MinecraftClient = MinecraftClient.getInstance()
     abstract val world: ClientWorld?

common/src/main/kotlin/com/lambda/context/ClientContext.kt

@@ -4,7 +4,20 @@ import net.minecraft.client.network.ClientPlayNetworkHandler
 import net.minecraft.client.network.ClientPlayerEntity
 import net.minecraft.client.network.ClientPlayerInteractionManager
 import net.minecraft.client.world.ClientWorld
+import net.minecraft.client.MinecraftClient
 
+/**
+ * A class extending the [AbstractContext] in the [MinecraftClient].
+ * This is considered the "unsafe" variant of the contexts as the properties can be null.
+ * Methods in this context will always need to perform null checks for type safety.
+ *
+ * @property world The world in which the player is currently located, or `null` if the world is not available.
+ * @property player The player entity, or `null` if the player is not available.
+ * @property interaction The interaction manager for the player, or `null` if the interaction manager is not available.
+ * @property connection The network handler for the player, or `null` if the network handler is not available.
+ *
+ * @function toSafe Converts the `ClientContext` to a `SafeContext` if all properties are not `null`, or returns `null` otherwise.
+ */
 open class ClientContext : AbstractContext() {
     final override val world: ClientWorld? = mc.world
     final override val player: ClientPlayerEntity? = mc.player

common/src/main/kotlin/com/lambda/context/SafeContext.kt

@@ -4,7 +4,31 @@ import net.minecraft.client.network.ClientPlayNetworkHandler
 import net.minecraft.client.network.ClientPlayerEntity
 import net.minecraft.client.network.ClientPlayerInteractionManager
 import net.minecraft.client.world.ClientWorld
+import net.minecraft.client.MinecraftClient
 
+/**
+ * A class extending the [AbstractContext] in the [MinecraftClient].
+ * This is considered the "safe" variant of the contexts as the properties are non-`null`.
+ * Methods in this context will not need to perform `null` checks for type safety.
+ *
+ * The [SafeContext] is used as a receiver in extension functions to bring the type-safe properties into scope.
+ * This allows methods to operate on the [MinecraftClient] without the need for type checks on the properties.
+ *
+ * Example usage:
+ * ```kotlin
+ * fun SafeContext.exampleFunction() {
+ *     // Here, we can directly access the properties without null checks
+ *     val playerName = player.name.asString()
+ *     val worldName = world.registryKey.value.path
+ *     // ...
+ * }
+ * ```
+ * 
+ * @property world The world in which the player is currently located.
+ * @property player The player entity.
+ * @property interaction The interaction manager for the player.
+ * @property connection The network handler for the player.
+ **/
 open class SafeContext internal constructor(
     override val world: ClientWorld,
     override val player: ClientPlayerEntity,

common/src/main/kotlin/com/lambda/event/cancellable/Cancellable.kt

@@ -2,6 +2,14 @@ package com.lambda.event.cancellable
 
 import java.util.concurrent.atomic.AtomicBoolean
 
+/**
+ * Used as delegate for [ICancellable] events.
+ *
+ * A `Cancellable` event is a type of [ICancellable] that can be cancelled.
+ * It has a [cancelSignal] which is an [AtomicBoolean] that indicates whether the event has been canceled.
+ *
+ * @property cancelSignal The signal that indicates whether the event has been canceled.
+ */
 open class Cancellable : ICancellable {
     override val cancelSignal = AtomicBoolean(false)
 }

common/src/main/kotlin/com/lambda/event/cancellable/ICancellable.kt

@@ -3,12 +3,26 @@ package com.lambda.event.cancellable
 import com.lambda.event.CallbackEvent
 import java.util.concurrent.atomic.AtomicBoolean
 
+/**
+ * Representing a cancellable [CallbackEvent] in the event system.
+ *
+ * An [ICancellable] event is a type of [CallbackEvent] that can be canceled using [cancel].
+ * It has a [cancelSignal] which is an [AtomicBoolean] that indicates whether the event has been canceled.
+ *
+ * @property cancelSignal The signal that indicates whether the event has been canceled.
+ */
 interface ICancellable : CallbackEvent {
     val cancelSignal: AtomicBoolean
 
+    /**
+     * Cancels the event.
+     */
     fun cancel() {
         cancelSignal.set(true)
     }
 
+    /**
+     * Checks whether the event has been canceled.
+     */
     fun isCanceled() = cancelSignal.get()
 }

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

@@ -8,9 +8,6 @@ import com.lambda.module.Module
 abstract class ClientEvent : Event {
     data object Shutdown : ClientEvent()
     data object Startup : ClientEvent()
-    data class ModuleToggle(val module: Module) : ClientEvent()
-    data class ModuleEnable(val module: Module) : ClientEvent()
-    data class ModuleDisable(val module: Module) : ClientEvent()
     data class ConfigLoaded(val configuration: Configuration) : ClientEvent()
     data class ConfigSaved(val configuration: Configuration) : ClientEvent()
 }

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

@@ -2,5 +2,14 @@ package com.lambda.event.events
 
 import com.lambda.event.cancellable.Cancellable
 import com.lambda.event.cancellable.ICancellable
+import com.lambda.event.EventFlow
 
+/**
+ * A class representing a [KeyPressEvent] in the event system ([EventFlow]).
+ *
+ * A [KeyPressEvent] is a type of event that is triggered when a key is pressed.
+ * It implements [ICancellable] interface, which means the event can be cancelled.
+ *
+ * @property key The key code of the key that was pressed.
+ */
 class KeyPressEvent(val key: Int) : ICancellable by Cancellable()

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

@@ -4,15 +4,37 @@ import com.lambda.event.Event
 import com.lambda.event.cancellable.Cancellable
 import com.lambda.event.cancellable.ICancellable
 import net.minecraft.network.packet.Packet
+import com.lambda.event.EventFlow
 
+/**
+ * An abstract class representing a [PacketEvent] in the [EventFlow].
+ *
+ * A [PacketEvent] is a type of [Event] that is triggered when a packet is sent or received.
+ * It has two subclasses: [Send] and [Receive],
+ * which are triggered when a packet is sent and received, respectively.
+ *
+ * Each subclass has two further subclasses: [Pre] and [Post],
+ * which are triggered before and after the packet is sent or received.
+ *
+ * The [PacketEvent] class is designed to be extended by any class that needs to react to packet events.
+ *
+ * @see Send
+ * @see Receive
+ */
 abstract class PacketEvent : Event {
+    /**
+     * Representing a [PacketEvent] that is triggered when a packet is sent.
+     * It has two subclasses: [Pre] and [Post], which are triggered before and after the packet is sent.
+     */
     abstract class Send : PacketEvent() {
         class Pre(val packet: Packet<*>) : Send(), ICancellable by Cancellable()
         class Post(val packet: Packet<*>) : Send()
     }
 
+    /**
+     * Representing a `PacketEvent` that is triggered when a packet is received.
+     * It has two subclasses: [Pre] and [Post], which are triggered before and after the packet is received.
+     */
     abstract class Receive : PacketEvent() {
         class Pre(val packet: Packet<*>) : Receive(), ICancellable by Cancellable()
         class Post(val packet: Packet<*>) : Receive()
-    }
-}

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

@@ -1,8 +1,27 @@
 package com.lambda.event.events
 
 import com.lambda.event.Event
+import com.lambda.event.EventFlow
 
+/**
+ * An abstract class representing a [TickEvent] in the [EventFlow].
+ *
+ * A [TickEvent] is a type of [Event] that is triggered at each tick of the game loop.
+ * It has two subclasses: [Pre] and [Post], which are triggered before and after the tick, respectively.
+ *
+ * The [TickEvent] class is designed to be extended by any class that needs to react to ticks.
+ *
+ * @see Pre
+ * @see Post
+ */
 abstract class TickEvent : Event {
+    /**
+     * A class representing a [TickEvent] that is triggered before each tick of the game loop.
+     */
     class Pre : TickEvent()
+
+    /**
+     * A class representing a [TickEvent] that is triggered after each tick of the game loop.
+     */
     class Post : TickEvent()
 }

common/src/main/kotlin/com/lambda/event/listener/Listener.kt

@@ -1,14 +1,52 @@
 package com.lambda.event.listener
 
 import com.lambda.event.Event
+import com.lambda.event.EventFlow
+import com.lambda.event.Muteable
+import com.lambda.module.Module
 
+/**
+ * An abstract class representing a [Listener] in the [Event] system ([EventFlow]).
+ *
+ * A [Listener] is an entity that reacts to specific [Event]s happening within the system.
+ * It has a [priority], an [owner],
+ * and a flag indicating whether it should always listen to [Event]s,
+ * even when the Object listening is [Muteable.isMuted] (e.g.: If it is a [Module] and not [Module.isEnabled]).
+ *
+ * The [Listener] class is not directly used to create listeners.
+ * Instead, it serves as a base for the [SafeListener] and [UnsafeListener] classes,
+ * which will trigger in different contexts (see [SafeListener] and [UnsafeListener]).
+ *
+ * The extending class needs to implement the [execute] method,
+ * which defines the actions to be taken when the [Event] occurs.
+ *
+ * [Listener]s can be sorted based on their [priority],
+ * if two [Listener]s have the same [priority], their order is determined by their [hashCode].
+ *
+ * @property priority The priority of the [Listener]. [Listener]s with higher [priority] are executed first.
+ * @property owner The owner of the [Listener]. This is typically the object that created the [Listener].
+ * @property alwaysListen If true, the [Listener] will always be triggered, even if the [owner] is not enabled.
+ */
 abstract class Listener : Comparable<Listener> {
     abstract val priority: Int
-    abstract val owner: Any // ToDo: Evaluate if this is even needed
+    abstract val owner: Any
     abstract val alwaysListen: Boolean
 
+    /**
+     * Executes the actions defined by this listener when the event occurs.
+     *
+     * @param event The event that triggered this listener.
+     */
     abstract fun execute(event: Event)
 
+    /**
+     * Compares this listener with another listener.
+     * The comparison is based first on the priority, and then on the hash code of the listeners.
+     *
+     * @param other The other listener to compare with.
+     * @return A negative integer, zero, or a positive integer as this listener is less than, equal to,
+     * or greater than the specified listener.
+     */
     override fun compareTo(other: Listener) =
         compareBy<Listener> {
             it.priority