add documentation

Author: EngineMachiner

src/client/kotlin/com/enginemachiner/harmony/client/Command.kt

@@ -4,15 +4,20 @@ import com.enginemachiner.harmony.Command
 import com.enginemachiner.harmony.CommandSetup
 import com.enginemachiner.harmony.HarmonyArgumentBuilder
 import com.mojang.brigadier.arguments.ArgumentType
-import com.mojang.brigadier.tree.CommandNode
-import net.fabricmc.fabric.api.client.command.v2.ClientCommandManager.literal
 import net.fabricmc.fabric.api.client.command.v2.ClientCommandManager.argument
+import net.fabricmc.fabric.api.client.command.v2.ClientCommandManager.literal
 import net.fabricmc.fabric.api.client.command.v2.FabricClientCommandSource
 
 private typealias ClientCommandType = Command<FabricClientCommandSource, ClientCommand>
 private typealias Builder = HarmonyArgumentBuilder<FabricClientCommandSource>
 private typealias Setup = CommandSetup<ClientCommand>
 
+/**
+ * Creates and configures a client-side command.
+ * @param name The name of the command
+ * @param setup The setup lambda to configure the command
+ * @return A configured CommandNode for registration
+ */
 fun clientCommand( name: String, setup: Setup ) = ClientCommand(name).apply(setup).build()
 
 class ClientCommand( builder: Builder ) : ClientCommandType(builder) {

src/client/kotlin/com/enginemachiner/harmony/client/KeyBinding.kt

@@ -11,6 +11,13 @@ class KeybindsManager( mod: Mod ) {
 
     private val id = mod.id
 
+    /**
+     * Creates and configures a key binding.
+     * @param subKey The key identifier suffix
+     * @param subCategory The category identifier suffix
+     * @param code The default key code (default: UNKNOWN)
+     * @param type The input type (default: KEYSYM)
+     */
     inner class Binder( subKey: String, subCategory: String, code: Int = Keys.UNKNOWN, type: InputUtil.Type = KEYSYM ) {
 
         val key = "key.$id.$subKey";             val category = "category.$id.$subCategory"
@@ -23,6 +30,7 @@ class KeybindsManager( mod: Mod ) {
 
 }
 
+/** Key code constants for common keyboard keys. */
 object Keys {
 
     const val F1 = GLFW.GLFW_KEY_F1

src/client/kotlin/com/enginemachiner/harmony/client/Networking.kt

@@ -12,10 +12,18 @@ import net.minecraft.network.PacketByteBuf
 /** Checks if the client has a network handler. */
 fun MinecraftClient.isConnected() = networkHandler != null
 
+/** Manages client-side networking for packet sending and receiving. */
 class ClientNetworking( private val mod: Mod ) {
 
     private fun id( path: String ) = mod.id(path)
 
+    /**
+     * Registers a receiver for deserialized packets.
+     *
+     * @param path The packet identifier path.
+     * @param packet The packet instance to deserialize into
+     * @param handler The handler lambda with deserialized packet context
+     */
     fun <T: Packet> receive( path: String, packet: T, handler: DeserializedContext<T>.() -> Unit ) {
 
         val id = id(path)
@@ -28,13 +36,19 @@ class ClientNetworking( private val mod: Mod ) {
 
     }
 
+    /** Sends a packet to the server. */
     fun send( path: String, packet: Packet ) {
 
         val id = id(path);              val buf = packet.write();               ClientPlayNetworking.send( id, buf )
 
     }
 
 
+    /**
+     * Registers a receiver for raw packet buffers.
+     * @param buf The packet buffer (unused in registration, context provides actual buffer)
+     * @param handler The handler lambda with raw buffer context
+     */
     fun receive( path: String, buf: PacketByteBuf, handler: RawContext.() -> Unit ) {
 
         val id = id(path)
@@ -47,6 +61,7 @@ class ClientNetworking( private val mod: Mod ) {
 
     }
 
+    /** Sends a raw packet buffer to the server. */
     fun send( path: String, buf: PacketByteBuf ) {
 
         val id = id(path);              ClientPlayNetworking.send( id, buf )

src/client/kotlin/com/enginemachiner/harmony/client/Renderer.kt

@@ -11,6 +11,7 @@ import net.minecraft.item.Item
 import net.minecraft.item.ItemConvertible
 import java.awt.Color
 
+/** Sets the shader color for rendering. */
 fun setShaderColor( color: Color ) {
 
     val color = color.getRGBComponents(null);           color.forEachIndexed { i, value -> color[i] = value / 255f }

src/client/kotlin/com/enginemachiner/harmony/client/Screen.kt

@@ -1,11 +1,8 @@
 package com.enginemachiner.harmony.client
 
-import com.mojang.blaze3d.systems.RenderSystem
-import com.mojang.blaze3d.systems.RenderSystem.setShaderColor
 import com.mojang.blaze3d.systems.RenderSystem.setShaderTexture
-import net.minecraft.client.gui.DrawableHelper
 import net.minecraft.client.gui.DrawableHelper.drawTexture
-import net.minecraft.client.gui.widget.*
+import net.minecraft.client.gui.widget.ClickableWidget
 import net.minecraft.client.util.math.MatrixStack
 import net.minecraft.text.OrderedText
 import net.minecraft.text.Text
@@ -27,7 +24,7 @@ interface Positionable {
 
 }
 
-// It trims by default.
+/** Wrapper for clickable widgets with automatic text trimming. */
 open class Widget( initPos: Vec2f, initSize: Vec2f, message: Text, val widget: ClickableWidget ) : Positionable {
 
     override var pos = initPos;         var size = initSize;            override fun size() = size
@@ -64,6 +61,7 @@ open class Widget( initPos: Vec2f, initSize: Vec2f, message: Text, val widget: C
 
 }
 
+/** Rendering text with automatic line wrapping. */
 abstract class HarmonyText( initPos: Vec2f, initText: Text, maxWidth: Float? = null ) : Positionable {
 
     var text = initText;    set(value) { field = value;    refresh() }

src/client/kotlin/com/enginemachiner/harmony/client/Tween.kt

@@ -6,16 +6,33 @@ import net.minecraft.util.math.MathHelper.lerpAngleDegrees
 import java.awt.Color
 import java.awt.Color.RGBtoHSB
 
+/**
+ * Base interface for objects that can be animated over time.
+ */
 interface Tweenable {
 
-    fun restart();          fun isDone(): Boolean
+    /** Restarts the animation from the beginning. */
+    fun restart()
 
-    fun delay( delay: Float );          fun update( delta: Float )
+    /** Returns true if the animation has completed. */
+    fun isDone(): Boolean
 
-}
+    /** Sets a delay in seconds before the animation starts. */
+    fun delay( delay: Float )
+
+    /** Updates the animation by the given delta time in ticks. */
+    fun update( delta: Float )
 
-// Duration in seconds.
+}
 
+/**
+ * Interpolates a value from [start] to [end] over a specified [duration].
+ *
+ * @param start The starting value.
+ * @param end The ending value.
+ * @param duration The duration of the tween in seconds.
+ * @param easing The easing enum to apply to the interpolation.
+ */
 open class Tween(
 
     private val start: Float,           private val end: Float,
@@ -27,14 +44,22 @@ open class Tween(
 
     override fun delay( delay: Float ) { this.delay = delay }
 
+    /**
+     * Returns the current progress of the tween as a value between 0 and 1.
+     */
     fun progress(): Float {
 
         var t = time - delay;           t = t.coerceIn( 0f, 1f );           return t / duration
 
     }
 
+    /**
+     * Interpolates between start and end values using the given progress [t].
+     * Can be overridden for custom interpolation behavior.
+     */
     open fun interpolate( t: Float ) = lerp( t, start, end )
 
+    /** Returns the current interpolated value with easing applied. */
     fun value(): Float {
 
         var t = progress();         t = easing.calculate(t);         return interpolate(t)
@@ -47,6 +72,10 @@ open class Tween(
 
 }
 
+/**
+ * A specialized tween for interpolating angles in degrees.
+ * Uses angular interpolation to handle wrapping around 360 degrees correctly.
+ */
 class AngleTween(
 
     private val start: Float,           private val end: Float,
@@ -58,14 +87,17 @@ class AngleTween(
 
 }
 
+/**
+ * A tween for smoothly interpolating between two colors in HSB color space.
+ * Interpolates hue as an angle for smooth color transitions.
+ */
 class ColorTween(
 
     start: Color,               end: Color,
     duration: Float,            easing: Easing = Easing.LINEAR
 
 ) : Tweenable {
 
-    // The hue is in range [0, 1] for RGBtoHSB() and lerpAngleDegrees() will work fine with it.
     private val startHSB = RGBtoHSB( start.red, start.green, start.blue, null )
     private val endHSB = RGBtoHSB( end.red, end.green, end.blue, null )
 
@@ -75,6 +107,7 @@ class ColorTween(
 
     private val group = TweenGroup( hue, saturation, brightness )
 
+    /** Returns the current interpolated color. */
     fun value(): Color {
 
         val hue = hue.value()
@@ -93,10 +126,20 @@ class ColorTween(
 
 }
 
+/**
+ * Groups multiple tweens to run simultaneously.
+ * The group is considered done when all tweens are done.
+ *
+ * @param tweens The tweens to group together.
+ */
 class TweenGroup( vararg tweens: Tweenable ) : Tweenable {
 
     private val tweens = tweens.toMutableList()
 
+    /**
+     * Adds additional tweens to this group.
+     * @return This group for method chaining.
+     */
     fun add( vararg tween: Tweenable ): TweenGroup { tweens.addAll(tween); return this }
 
     override fun delay( delay: Float ) { tweens.forEach { it.delay(delay) } }
@@ -109,17 +152,29 @@ class TweenGroup( vararg tweens: Tweenable ) : Tweenable {
 
 }
 
+/**
+ * Runs multiple tweens in sequence, one after another.
+ * Each tween starts when the previous one completes.
+ *
+ * @param tweens The tweens to run in sequence.
+ */
 class TweenSequence( vararg tweens: Tweenable ) : Tweenable {
 
+    /**
+     * Returns the currently active tween in the sequence.
+     */
     fun currentTween() = tweens[i]
 
     private var i = 0;          private val tweens = tweens.toMutableList()
 
+    /**
+     * Adds additional tweens to run after the current sequence.
+     * @return This sequence for method chaining.
+     */
     fun then( vararg tween: Tweenable ): TweenSequence { tweens.addAll(tween); return this }
 
     override fun delay( delay: Float ) { currentTween().delay(delay) }
 
-    // Move to next tween when current tween is done.
     override fun update( delta: Float ) {
 
         if ( isDone() ) return;         val tween = currentTween()

src/main/java/com/enginemachiner/harmony/mixin/PlayerInventoryMixin.java

@@ -12,19 +12,34 @@
 import org.spongepowered.asm.mixin.injection.Inject;
 import org.spongepowered.asm.mixin.injection.callback.CallbackInfo;
 
+/**
+ * Mixin for {@link PlayerInventory} to track item stack changes and notify modded items.
+ */
 @Mixin( PlayerInventory.class )
 public abstract class PlayerInventoryMixin implements Inventory {
 
+    /**
+     * Stores the previous item stack before it's replaced.
+     * Used to compare old and new stacks when notifying modded items of inventory changes.
+     */
     @Unique
     private ItemStack oldStack = ItemStack.EMPTY;
 
+    /**
+     * Captures the old item stack before it's replaced.
+     * Injected at the HEAD of {@code setStack} to save the current stack.
+     */
     @Inject( at = @At("HEAD"), method = "setStack(ILnet/minecraft/item/ItemStack;)V" )
     private void harmonySetOldStack( int slot, ItemStack newStack, CallbackInfo callback ) {
 
         oldStack = getStack(slot).copy();
 
     }
 
+    /**
+     * Notifies modded items when their stack changes in the inventory.
+     * Injected at the TAIL of {@code setStack} after the stack has been replaced.
+     */
     @Inject( at = @At("TAIL"), method = "setStack(ILnet/minecraft/item/ItemStack;)V" )
     private void harmonyOnStackSet( int slot, ItemStack newStack, CallbackInfo callback ) {
 

src/main/kotlin/com/enginemachiner/harmony/Advancement.kt

@@ -8,9 +8,13 @@ import net.minecraft.text.Text
 import net.minecraft.util.Identifier
 import java.util.function.Consumer
 
-/** Advancement builder for custom advancements in Data Generation. */
+/**
+ * Abstract builder to create custom advancements when generating data.
+ * Provides a structured way to define advancement properties and to build them.
+ */
 abstract class AdvancementBuilder {
 
+    /** Set after calling [build]. */
     lateinit var advancement: Advancement
 
     open val parent: AdvancementBuilder? = null
@@ -27,6 +31,10 @@ abstract class AdvancementBuilder {
     abstract val criterion: String
     abstract val conditions: CriterionConditions
 
+    /**
+     * Hook for additional builder configuration.
+     * Override to add custom criteria or other builder settings.
+     */
     open fun configureBuilder( builder: Advancement.Builder ) {}
 
     abstract fun id(): String
@@ -51,8 +59,15 @@ abstract class AdvancementBuilder {
 
 }
 
+/** Advancement builder factory for a specific mod. */
 class ModAdvancement( private val mod: Mod ) {
 
+    /**
+     * Base builder for mod-specific advancements.
+     * Automatically configures title, description, and ID based on the mod and path.
+     *
+     * @param path The advancement path within the mod namespace.
+     */
     abstract inner class Builder( val path: String ) : AdvancementBuilder() {
 
         val translation = mod.translation.advancement

src/main/kotlin/com/enginemachiner/harmony/Chat.kt

@@ -4,8 +4,10 @@ import net.minecraft.text.Text
 import net.minecraft.text.MutableText
 import net.minecraft.util.Formatting
 
+/** Provides chat message formatting utilities for a mod. */
 open class Chat( private val mod: Mod ) {
 
+    /** Creates a formatted title prefix for chat messages. */
     open fun title(): MutableText {
 
         val name = mod.name.uppercase();            val gray = Formatting.GRAY

src/main/kotlin/com/enginemachiner/harmony/Collection.kt

@@ -7,8 +7,7 @@ package com.enginemachiner.harmony
  * @param value The element to start from
  * @param offset The number of positions to move (positive or negative)
  * @return The element at the calculated position
- * @throws NoSuchElementException if the collection is empty
- * @throws NoSuchElementException if the collection doesn't contain the specified [value]
+ * @throws NoSuchElementException if the collection is empty or the collection doesn't contain the specified [value]
  *
  */
 fun <T> Collection<T>.cycle( value: T, offset: Int = 1 ): T {