From 70d1d72b8369ec99f0c4130ab5a3513bb5eb3fa8 Mon Sep 17 00:00:00 2001
From: PeaAshMeter <ivanyr44@gmail.com>
Date: Thu, 23 Oct 2025 19:21:06 +0300
Subject: [PATCH] Add detailed comments to AnimationNode explaining its
 behavior and usage example

---
 lib/animation_node.lua | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/lib/animation_node.lua b/lib/animation_node.lua
index 25b3e19..f3ef786 100644
--- a/lib/animation_node.lua
+++ b/lib/animation_node.lua
@@ -1,6 +1,26 @@
 --- @alias voidCallback fun(): nil
 --- @alias animationRunner fun(node: AnimationNode)
 
+--- Узел дерева анимаций.
+---
+--- Отслеживает завершение всех анимаций всех дочерних узлов и оповещает вышестоящий узел.
+---
+--- Дочерние узлы одного уровня запускают свою анимацию одновременно после завершения анимации родителя.
+--- Example:
+--- ```lua
+---     AnimationNode {
+---         function (node) residentsleeper:sleep(1000, node) end, -- must pass itself down as the parameter
+---         onEnd = function() print("completed") end,
+---         children = { -- children run in parallel after the parent animation is completed
+---             AnimationNode {
+---                 function (node) sprite:animate("attack", node) end
+---             },
+---             AnimationNode {
+---                 function (node) other_sprite:animate("hurt", node) end
+---             },
+---         }
+---     }:run()
+--- ```
 --- @class AnimationNode
 --- @field count integer
 --- @field run animationRunner