Add more comments

Author: valkyrienyanko

.githooks/pre-commit

@@ -20,7 +20,7 @@ set -euo pipefail
 
 # dotnet format mode: whitespace or full.
 # whitespace is faster for commit-time checks while still using dotnet format.
-: "${PRECOMMIT_FORMAT_MODE:=whitespace}"
+: "${PRECOMMIT_FORMAT_MODE:=full}"
 
 # true: run targeted builds for changed project areas.
 : "${PRECOMMIT_ENABLE_BUILD_GODOTUTILS:=true}"

Template.GodotUtils/Debugging/JsonExceptionHandler.cs

@@ -15,45 +15,41 @@ public static class JsonExceptionHandler
     private const int ContextLinesAfter = 8;
 
     /// <summary>
-    /// Prints a formatted JSON parsing error with context.
+    /// Prints a formatted JSON parsing error with nearby source context when line data is available.
     /// </summary>
+    /// <param name="ex">JSON exception describing the parse failure.</param>
+    /// <param name="jsonText">Original JSON source text.</param>
+    /// <param name="path">Path of the JSON resource being parsed.</param>
     public static void Handle(JsonException ex, string jsonText, string path)
     {
-        // Extract relevant information from the exception
         long? lineNumber = ex.LineNumber;
 
+        // Prefer context-rich output when the parser reports a source line number.
         if (lineNumber.HasValue)
         {
-            // Split the JSON into lines
             string[] lines = jsonText.Split('\n');
 
-            // Get the problematic line
             int lineIndex = (int)lineNumber.Value;
             lineIndex = Math.Clamp(lineIndex, 0, Math.Max(0, lines.Length - 1));
             string problematicLine = lines[lineIndex];
 
-            // Determine the range of lines to display
             int startLine = Math.Max(0, lineIndex - ContextLinesBefore);
             int endLine = Math.Min(lines.Length, lineIndex + ContextLinesAfter);
 
-            // Create the error message
             StringBuilder errorMessage = new();
 
             errorMessage.AppendLine($"ERROR: Failed to parse {Path.GetFileName(path)}");
             errorMessage.AppendLine();
             errorMessage.AppendLine($"{ex.Message}");
             errorMessage.AppendLine();
 
-            // Add the lines before the problematic line
             for (int i = startLine; i < lineIndex; i++)
             {
                 errorMessage.AppendLine(lines[i]);
             }
 
-            // Add the problematic line with the caret indicating the error position
             errorMessage.AppendLine($"{problematicLine} <--- Syntax error could be on this line or the next line");
 
-            // Add the lines after the problematic line
             for (int i = lineIndex + 1; i < endLine; i++)
             {
                 errorMessage.AppendLine(lines[i]);

Template.GodotUtils/Debugging/ParamValidator.cs

@@ -11,12 +11,17 @@ namespace GodotUtils.Debugging;
 public static class ParamValidator
 {
     /// <summary>
-    /// Throws when <paramref name="obj"/> is null and disables the node.
+    /// Validates an object argument and disables the node before throwing when the value is null.
     /// </summary>
+    /// <param name="node">Node to disable when validation fails.</param>
+    /// <param name="obj">Argument value to validate.</param>
+    /// <param name="paramName">Name of the validated argument.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="obj"/> is null.</exception>
     public static void ThrowIfNull(Node node, object obj, [CallerArgumentExpression(nameof(obj))] string paramName = "")
     {
         ArgumentNullException.ThrowIfNull(node, nameof(node));
 
+        // Disable processing before throwing so invalid nodes stop running immediately.
         if (obj == null)
         {
             Script script = node.GetScript().As<Script>();

Template.GodotUtils/Deprecated/EventManager.cs

@@ -7,6 +7,7 @@ namespace GodotUtils.Deprecated;
 /// <summary>
 /// Legacy event manager for dispatching events by enum key.
 /// </summary>
+/// <typeparam name="TEvent">Enum key type used to group and dispatch listeners.</typeparam>
 // This class was created to attempt to simplify the process of creating C# events for gamedev.
 // 
 // ########### Example #1 ###########
@@ -40,6 +41,9 @@ public class EventManager<TEvent> where TEvent : notnull
     /// <summary>
     /// Adds a listener that receives raw argument arrays.
     /// </summary>
+    /// <param name="eventType">Event key to subscribe to.</param>
+    /// <param name="action">Callback invoked with all notify arguments.</param>
+    /// <param name="id">Optional identifier used for grouped removal.</param>
     public void AddListener(TEvent eventType, Action<object[]> action, string id = "")
     {
         AddListenerInternal(eventType, action, id);
@@ -48,6 +52,10 @@ public void AddListener(TEvent eventType, Action<object[]> action, string id = "
     /// <summary>
     /// Adds a typed listener that receives the first argument as <typeparamref name="T"/>.
     /// </summary>
+    /// <typeparam name="T">Expected type of the first notify argument.</typeparam>
+    /// <param name="eventType">Event key to subscribe to.</param>
+    /// <param name="action">Typed callback invoked with the first notify argument.</param>
+    /// <param name="id">Optional identifier used for grouped removal.</param>
     public void AddListener<T>(TEvent eventType, Action<T> action, string id = "")
     {
         AddListenerInternal(eventType, WrapAction(action), id);
@@ -56,13 +64,17 @@ public void AddListener<T>(TEvent eventType, Action<T> action, string id = "")
     /// <summary>
     /// Removes all listeners of type <paramref name="eventType"/> with the provided id.
     /// </summary>
+    /// <param name="eventType">Event key whose listeners should be filtered.</param>
+    /// <param name="id">Identifier used to match listener entries for removal.</param>
     public void RemoveListeners(TEvent eventType, string id = "")
     {
+        // Removing from an unknown event type is treated as a usage error.
         if (!_eventListeners.TryGetValue(eventType, out List<Listener>? listeners))
             throw new InvalidOperationException($"Tried to remove listener of event type '{eventType}' from an event type that has not even been defined yet");
 
         for (int i = listeners.Count - 1; i >= 0; i--)
         {
+            // Remove all listener entries that match the target id.
             if (listeners[i].Id == id)
                 listeners.RemoveAt(i);
         }
@@ -79,21 +91,32 @@ public void RemoveAllListeners()
     /// <summary>
     /// Notifies all listeners for the provided event type.
     /// </summary>
+    /// <param name="eventType">Event key to dispatch.</param>
+    /// <param name="args">Arguments passed through to each listener callback.</param>
     public void Notify(TEvent eventType, params object[] args)
     {
+        // Unknown event types simply have no listeners to notify.
         if (!_eventListeners.TryGetValue(eventType, out List<Listener>? value))
         {
             return;
         }
 
+        // Iterate snapshot to avoid collection-modified issues during callbacks.
         foreach (Listener listener in value.ToList()) // if ToList() is not here then issue #137 will occur
         {
             ((Action<object[]>)listener.Action)(args);
         }
     }
 
+    /// <summary>
+    /// Registers a raw listener for the given event type, creating the listener list when needed.
+    /// </summary>
+    /// <param name="eventType">Event key used to group listeners.</param>
+    /// <param name="action">Listener callback that receives the notify argument array.</param>
+    /// <param name="id">Optional listener identifier used by removal APIs.</param>
     private void AddListenerInternal(TEvent eventType, Action<object[]> action, string id)
     {
+        // Lazily create listener bucket for first subscription of an event type.
         if (!_eventListeners.TryGetValue(eventType, out List<Listener>? listeners))
         {
             listeners = [];
@@ -103,10 +126,17 @@ private void AddListenerInternal(TEvent eventType, Action<object[]> action, stri
         listeners.Add(new Listener(action, id));
     }
 
+    /// <summary>
+    /// Wraps a typed listener so it can be invoked by the raw object-array dispatch pipeline.
+    /// </summary>
+    /// <typeparam name="T">Expected argument type at index zero.</typeparam>
+    /// <param name="action">Typed listener callback.</param>
+    /// <returns>Adapter callback compatible with raw listener storage.</returns>
     private static Action<object[]> WrapAction<T>(Action<T> action)
     {
         return args =>
         {
+            // Typed listeners consume only the first argument when available.
             if (args == null || args.Length == 0)
                 return;
 
@@ -118,6 +148,8 @@ private static Action<object[]> WrapAction<T>(Action<T> action)
 /// <summary>
 /// Stores a listener delegate and identifier.
 /// </summary>
+/// <param name="action">Callback delegate to invoke during event dispatch.</param>
+/// <param name="id">Optional identifier used for listener removal filters.</param>
 public class Listener(dynamic action, string id)
 {
     /// <summary>

Template.GodotUtils/Extensions/AnimatedSprite2DExtensions.cs

@@ -10,6 +10,8 @@ public static class AnimatedSprite2DExtensions
     /// <summary>
     /// Plays an animation immediately without the usual switch delay.
     /// </summary>
+    /// <param name="sprite">Animated sprite to update.</param>
+    /// <param name="anim">Animation name to play.</param>
     public static void InstantPlay(this AnimatedSprite2D sprite, string anim)
     {
         sprite.Animation = anim;
@@ -19,16 +21,21 @@ public static void InstantPlay(this AnimatedSprite2D sprite, string anim)
     /// <summary>
     /// Plays an animation immediately at the provided frame.
     /// </summary>
+    /// <param name="sprite">Animated sprite to update.</param>
+    /// <param name="anim">Animation name to play.</param>
+    /// <param name="frame">Frame index to set before playback starts.</param>
     public static void InstantPlay(this AnimatedSprite2D sprite, string anim, int frame)
     {
         sprite.Animation = anim;
 
         int frameCount = sprite.SpriteFrames.GetFrameCount(anim);
 
+        // Apply requested frame only when index is within animation bounds.
         if (frameCount - 1 >= frame)
         {
             sprite.Frame = frame;
         }
+        // Log out-of-range frame selection for debugging.
         else
         {
             GD.Print($"The frame '{frame}' specified for {sprite.Name} is " +
@@ -41,6 +48,8 @@ public static void InstantPlay(this AnimatedSprite2D sprite, string anim, int fr
     /// <summary>
     /// Plays an animation starting at a random frame.
     /// </summary>
+    /// <param name="sprite">Animated sprite to update.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
     public static void PlayRandom(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -51,6 +60,9 @@ public static void PlayRandom(this AnimatedSprite2D sprite, string anim = "")
     /// <summary>
     /// Gets the unscaled size of the first frame.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Width and height of frame zero before node scaling.</returns>
     public static Vector2 GetSize(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -63,6 +75,9 @@ public static Vector2 GetSize(this AnimatedSprite2D sprite, string anim = "")
     /// <summary>
     /// Gets the scaled size of the first frame.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Width and height of frame zero after node scaling.</returns>
     public static Vector2 GetScaledSize(this AnimatedSprite2D sprite, string anim = "")
     {
         Vector2 size = sprite.GetSize(anim);
@@ -73,6 +88,9 @@ public static Vector2 GetScaledSize(this AnimatedSprite2D sprite, string anim =
     /// <summary>
     /// Gets the visible pixel size after trimming transparent borders.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Visible pixel width and height after transparency trimming.</returns>
     public static Vector2 GetPixelSize(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -82,6 +100,9 @@ public static Vector2 GetPixelSize(this AnimatedSprite2D sprite, string anim = "
     /// <summary>
     /// Gets the visible pixel width after trimming transparent columns.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Visible width in pixels after transparency trimming and scaling.</returns>
     public static int GetPixelWidth(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -98,6 +119,9 @@ public static int GetPixelWidth(this AnimatedSprite2D sprite, string anim = "")
     /// <summary>
     /// Gets the visible pixel height after trimming transparent rows.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Visible height in pixels after transparency trimming and scaling.</returns>
     public static int GetPixelHeight(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -114,6 +138,9 @@ public static int GetPixelHeight(this AnimatedSprite2D sprite, string anim = "")
     /// <summary>
     /// Gets the offset from the bottom to the first opaque pixel.
     /// </summary>
+    /// <param name="sprite">Animated sprite that owns the animation frames.</param>
+    /// <param name="anim">Optional animation name, or empty to use the current animation.</param>
+    /// <returns>Pixel distance from the frame bottom to the first opaque center pixel.</returns>
     public static int GetPixelBottomY(this AnimatedSprite2D sprite, string anim = "")
     {
         string resolvedAnim = ResolveAnimation(sprite, anim);
@@ -125,6 +152,7 @@ public static int GetPixelBottomY(this AnimatedSprite2D sprite, string anim = ""
 
         for (int y = size.Y - 1; y >= 0; y--)
         {
+            // Stop once an opaque pixel is reached in center column.
             if (img.GetPixel(size.X / 2, y).A != 0)
             {
                 break;
@@ -136,11 +164,24 @@ public static int GetPixelBottomY(this AnimatedSprite2D sprite, string anim = ""
         return diff;
     }
 
+    /// <summary>
+    /// Returns the requested animation name or falls back to the sprite's current animation.
+    /// </summary>
+    /// <param name="sprite">Animated sprite that provides the fallback animation.</param>
+    /// <param name="anim">Requested animation name.</param>
+    /// <returns>Resolved animation name to use for frame lookups.</returns>
     private static string ResolveAnimation(AnimatedSprite2D sprite, string anim)
     {
         return string.IsNullOrWhiteSpace(anim) ? sprite.Animation : anim;
     }
 
+    /// <summary>
+    /// Gets the first frame image for an animation and outputs its dimensions.
+    /// </summary>
+    /// <param name="sprite">Animated sprite that owns the frame set.</param>
+    /// <param name="anim">Animation name used for frame retrieval.</param>
+    /// <param name="size">Resolved frame image dimensions.</param>
+    /// <returns>Image for frame zero of the resolved animation.</returns>
     private static Image GetFrameImage(AnimatedSprite2D sprite, string anim, out Vector2I size)
     {
         Texture2D tex = sprite.SpriteFrames.GetFrameTexture(anim, 0);

Template.GodotUtils/Extensions/AnimationTreeExtensions.cs

@@ -10,6 +10,9 @@ public static class AnimationTreeExtensions
     /// <summary>
     /// Sets a condition briefly and auto-resets after 0.1 seconds.
     /// </summary>
+    /// <param name="tree">Animation tree to update.</param>
+    /// <param name="path">Condition parameter path segment.</param>
+    /// <param name="value">Condition value to set briefly.</param>
     public static void SetCondition(this AnimationTree tree, StringName path, bool value)
     {
         tree.SetParam($"conditions/{path}", value);
@@ -22,6 +25,9 @@ public static void SetCondition(this AnimationTree tree, StringName path, bool v
     /// <summary>
     /// Sets the blend position of a BlendSpace1D by name.
     /// </summary>
+    /// <param name="tree">Animation tree to update.</param>
+    /// <param name="name">Blend space parameter name.</param>
+    /// <param name="value">Blend position value.</param>
     public static void SetBlendSpace1DPosition(this AnimationTree tree, StringName name, float value)
     {
         tree.SetParam($"{name}/blend_position", value);
@@ -30,6 +36,9 @@ public static void SetBlendSpace1DPosition(this AnimationTree tree, StringName n
     /// <summary>
     /// Sets a parameter value on the animation tree.
     /// </summary>
+    /// <param name="tree">Animation tree to update.</param>
+    /// <param name="path">Parameter path segment under <c>parameters/</c>.</param>
+    /// <param name="value">Value to assign.</param>
     public static void SetParam(this AnimationTree tree, StringName path, Variant value)
     {
         tree.Set($"parameters/{path}", value);
@@ -38,6 +47,9 @@ public static void SetParam(this AnimationTree tree, StringName path, Variant va
     /// <summary>
     /// Gets a parameter value from the animation tree.
     /// </summary>
+    /// <param name="tree">Animation tree to read.</param>
+    /// <param name="path">Parameter path segment under <c>parameters/</c>.</param>
+    /// <returns>Resolved parameter value.</returns>
     public static Variant GetParam(this AnimationTree tree, StringName path)
     {
         return tree.Get($"parameters/{path}");
@@ -46,6 +58,9 @@ public static Variant GetParam(this AnimationTree tree, StringName path)
     /// <summary>
     /// Gets a condition value from the animation tree.
     /// </summary>
+    /// <param name="tree">Animation tree to read.</param>
+    /// <param name="path">Condition path segment under <c>conditions/</c>.</param>
+    /// <returns>Resolved condition value.</returns>
     public static bool GetCondition(this AnimationTree tree, StringName path)
     {
         return (bool)tree.GetParam($"conditions/{path}");
@@ -54,6 +69,8 @@ public static bool GetCondition(this AnimationTree tree, StringName path)
     /// <summary>
     /// Gets the state machine playback controller.
     /// </summary>
+    /// <param name="tree">Animation tree to read.</param>
+    /// <returns>State machine playback controller.</returns>
     public static AnimationNodeStateMachinePlayback GetStateMachine(this AnimationTree tree)
     {
         return tree.Get("parameters/playback").As<AnimationNodeStateMachinePlayback>();

Template.GodotUtils/Extensions/Area2DExtensions.cs

@@ -10,6 +10,8 @@ public static class Area2DExtensions
     /// <summary>
     /// Sets Monitoring using deferred property updates.
     /// </summary>
+    /// <param name="area">Area to update.</param>
+    /// <param name="enabled">Target monitoring state.</param>
     public static void SetMonitoringDeferred(this Area2D area, bool enabled)
     {
         area.SetDeferred(Area2D.PropertyName.Monitoring, enabled);
@@ -18,6 +20,8 @@ public static void SetMonitoringDeferred(this Area2D area, bool enabled)
     /// <summary>
     /// Sets Monitorable using deferred property updates.
     /// </summary>
+    /// <param name="area">Area to update.</param>
+    /// <param name="enabled">Target monitorable state.</param>
     public static void SetMonitorableDeferred(this Area2D area, bool enabled)
     {
         area.SetDeferred(Area2D.PropertyName.Monitorable, enabled);