docs(dev): improve code documentation and comments

- Add detailed documentation for EVENT_QUEUE_THRESHOLD constant explaining the heuristic for game state stability
- Document DebugPlus integration with reference to GitHub repo and optional dependency behavior
- Enhance assert_error_response docstring with parameter descriptions and usage details

Co-Authored-By: Claude <noreply@anthropic.com>

Author: S1M0N38

src/lua/api.lua

@@ -4,6 +4,11 @@ local json = require("json")
 -- Constants
 local UDP_BUFFER_SIZE = 65536
 local SOCKET_TIMEOUT = 0
+-- The threshold for determining when game state transitions are complete.
+-- This value represents the maximum number of events allowed in the game's event queue
+-- to consider the game idle and waiting for user action. When the queue has fewer than
+-- 3 events, the game is considered stable enough to process API responses. This is a
+-- heuristic based on empirical testing to ensure smooth gameplay without delays.
 local EVENT_QUEUE_THRESHOLD = 3
 API = {}
 API.socket = nil

src/lua/utils.lua

@@ -111,7 +111,12 @@ function utils.table_to_json(obj, depth)
   return json.encode(sanitized)
 end
 
--- Load debug
+-- Load DebugPlus integration
+-- Attempt to load the optional DebugPlus mod (https://github.com/WilsontheWolf/DebugPlus/tree/master).
+-- DebugPlus is a Balatro mod that provides additional debugging utilities for mod development,
+-- such as custom debug commands and structured logging. It is not required for core functionality
+-- and is primarily intended for development and debugging purposes. If the module is unavailable
+-- or incompatible, the program will continue to function without it.
 local success, dpAPI = pcall(require, "debugplus-api")
 
 if success and dpAPI.isVersionCompatible(1) then

tests/conftest.py

@@ -71,7 +71,20 @@ def send_and_receive_api_message(
 
 
 def assert_error_response(response, expected_error_text, expected_context_keys=None):
-    """Helper function to assert error response format and content."""
+    """
+    Helper function to assert the format and content of an error response.
+
+    Args:
+        response (dict): The response dictionary to validate. Must contain at least
+            the keys "error" and "state".
+        expected_error_text (str): The expected error message text to check within
+            the "error" field of the response.
+        expected_context_keys (list, optional): A list of keys expected to be present
+            in the "context" field of the response, if the "context" field exists.
+
+    Raises:
+        AssertionError: If the response does not match the expected format or content.
+    """
     assert isinstance(response, dict)
     assert "error" in response
     assert "state" in response