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

@@ -58,6 +58,7 @@ public void AddListener<T>(TEvent eventType, Action<T> action, string id = "")
     /// </summary>
     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");
 
@@ -81,11 +82,13 @@ public void RemoveAllListeners()
     /// </summary>
     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);
@@ -94,6 +97,7 @@ public void Notify(TEvent eventType, params object[] args)
 
     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 = [];
@@ -107,6 +111,7 @@ 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;
 

Template.GodotUtils/Extensions/AnimatedSprite2DExtensions.cs

@@ -25,10 +25,12 @@ public static void InstantPlay(this AnimatedSprite2D sprite, string anim, int fr
 
         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 " +
@@ -125,6 +127,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;

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);

Template.GodotUtils/Extensions/Area3DExtensions.cs

@@ -10,6 +10,8 @@ public static class Area3DExtensions
     /// <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 Area3D area, bool enabled)
     {
         area.SetDeferred(Area3D.PropertyName.Monitoring, enabled);
@@ -18,6 +20,8 @@ public static void SetMonitoringDeferred(this Area3D 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 Area3D area, bool enabled)
     {
         area.SetDeferred(Area3D.PropertyName.Monitorable, enabled);

Template.GodotUtils/Extensions/Camera2DExtensions.cs

@@ -10,6 +10,8 @@ public static class Camera2DExtensions
     /// <summary>
     /// Sets the camera position without smoothing, then restores smoothing if needed.
     /// </summary>
+    /// <param name="camera">Camera to reposition.</param>
+    /// <param name="position">Target position.</param>
     public static void SetPositionIgnoreSmoothing(this Camera2D camera, Vector2 position)
     {
         bool smoothEnabled = camera.PositionSmoothingEnabled;
@@ -24,6 +26,7 @@ public static void SetPositionIgnoreSmoothing(this Camera2D camera, Vector2 posi
 
         if (smoothEnabled)
         {
+            // Restore smoothing after the snapped position has been applied.
             Tweens.Delay(camera, 0.01, () => camera.PositionSmoothingEnabled = true);
         }
     }

Template.GodotUtils/Extensions/CanvasItemExtensions.cs

@@ -10,6 +10,7 @@ public static class CanvasItemExtensions
     /// <summary>
     /// Applies an unshaded material to the canvas item.
     /// </summary>
+    /// <param name="canvasItem">Canvas item to modify.</param>
     public static void SetUnshaded(this CanvasItem canvasItem)
     {
         canvasItem.Material = new CanvasItemMaterial
@@ -21,6 +22,8 @@ public static void SetUnshaded(this CanvasItem canvasItem)
     /// <summary>
     /// Converts the canvas item position to a screen position.
     /// </summary>
+    /// <param name="canvasItem">Canvas item to project into screen coordinates.</param>
+    /// <returns>Screen position of the canvas item origin.</returns>
     public static Vector2 GetScreenPosition(this CanvasItem canvasItem)
     {
         // Code retrieved from https://www.reddit.com/r/godot/comments/1aq1f0b/comment/kqa6z0u/
@@ -34,6 +37,8 @@ public static Vector2 GetScreenPosition(this CanvasItem canvasItem)
     /// <summary>
     /// Sets the canvas item fully transparent and returns it.
     /// </summary>
+    /// <param name="canvasItem">Canvas item to modify.</param>
+    /// <returns>The same canvas item instance.</returns>
     public static CanvasItem SetTransparent(this CanvasItem canvasItem)
     {
         canvasItem.SelfModulate = new Color(1, 1, 1, 0);