--- a/libmlk-core/mlk/core/action-stack.h	Fri Mar 03 19:45:00 2023 +0100
+++ b/libmlk-core/mlk/core/action-stack.h	Sat Mar 04 08:52:57 2023 +0100
@@ -19,6 +19,17 @@
 #ifndef MLK_CORE_ACTION_STACK_H
 #define MLK_CORE_ACTION_STACK_H
 
+/**
+ * \file mlk/core/action-stack.h
+ * \brief Convenient stack of actions.
+ *
+ * Stack of actions.
+ *
+ * The purpose of this module is to help managing several actions at once.
+ * Actions are automatically removed from the stack if the corresponding update
+ * member function returns non-zero after completion.
+ */
+
 #include <stddef.h>
 
 #include "core.h"
@@ -27,36 +38,118 @@
 
 union mlk_event;
 
+/**
+ * \struct mlk_action_stack
+ * \brief Action stack structure
+ *
+ * This structure holds references to actions to be executed.
+ */
 struct mlk_action_stack {
+	/**
+	 * (read-write, borrowed)
+	 *
+	 * Array of non-owning actions to run.
+	 */
 	struct mlk_action **actions;
+
+	/**
+	 * (read-write)
+	 *
+	 * Number of actions in array ::mlk_action_script::actions
+	 *
+	 * \warning changing this value must be kept in sync with the array
+	 *          dimension.
+	 */
 	size_t actionsz;
 };
 
 MLK_CORE_BEGIN_DECLS
 
+/**
+ * Initialize the action sequence structure.
+ *
+ * This function will set all pointers in the ::mlk_action_stack::actions to
+ * NULL.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ */
 void
-mlk_action_stack_init(struct mlk_action_stack *, struct mlk_action **, size_t);
-
-int
-mlk_action_stack_add(struct mlk_action_stack *, struct mlk_action *);
+mlk_action_stack_init(struct mlk_action_stack *stack);
 
-void
-mlk_action_stack_start(struct mlk_action_stack *);
+/**
+ * Try to append a new action into the stack if one slot in the
+ * ::mlk_action_stack::actions is NULL
+ *
+ * The action is inserted as-is and ownership is left to the caller.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ * \param action the action to append
+ * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ */
+int
+mlk_action_stack_add(struct mlk_action_stack *stack,
+                     struct mlk_action *action);
 
-void
-mlk_action_stack_handle(struct mlk_action_stack *, const union mlk_event *);
+/**
+ * Tells if there are still at least one action in the stack.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ * \return non-zero if completed
+ */
+int
+mlk_action_stack_completed(const struct mlk_action_stack *stack);
+
 
-int
-mlk_action_stack_update(struct mlk_action_stack *, unsigned int);
+/**
+ * Invoke ::mlk_action_start on all actions.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ */
+void
+mlk_action_stack_start(struct mlk_action_stack *stack);
 
+/**
+ * Invoke ::mlk_action_handle on all actions.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ * \param event the event
+ */
 void
-mlk_action_stack_draw(const struct mlk_action_stack *);
+mlk_action_stack_handle(struct mlk_action_stack *stack,
+                        const union mlk_event *event);
 
+/**
+ * Invoke ::mlk_action_update on all actions.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ * \param ticks frame ticks
+ */
 int
-mlk_action_stack_completed(const struct mlk_action_stack *);
+mlk_action_stack_update(struct mlk_action_stack *stack,
+                        unsigned int ticks);
 
+/**
+ * Invoke ::mlk_action_draw on all actions.
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ */
 void
-mlk_action_stack_finish(struct mlk_action_stack *);
+mlk_action_stack_draw(const struct mlk_action_stack *stack);
+
+/**
+ *
+ * \pre stack != NULL
+ * \param stack the action stack
+ */
+void
+mlk_action_stack_finish(struct mlk_action_stack *stack);
 
 MLK_CORE_END_DECLS