--- a/libmlk-core/mlk/core/action-stack.c	Sat Mar 04 14:23:59 2023 +0100
+++ b/libmlk-core/mlk/core/action-stack.c	Sat Mar 04 14:42:03 2023 +0100
@@ -51,18 +51,6 @@
 	return MLK_ERR_NO_MEM;
 }
 
-void
-mlk_action_stack_start(struct mlk_action_stack *st)
-{
-	assert(st);
-
-	struct mlk_action *act;
-
-	FOREACH(st, act)
-		if (act)
-			mlk_action_start(act);
-}
-
 int
 mlk_action_stack_completed(const struct mlk_action_stack *st)
 {
@@ -78,6 +66,18 @@
 }
 
 void
+mlk_action_stack_start(struct mlk_action_stack *st)
+{
+	assert(st);
+
+	struct mlk_action *act;
+
+	FOREACH(st, act)
+		if (act)
+			mlk_action_start(act);
+}
+
+void
 mlk_action_stack_handle(struct mlk_action_stack *st, const union mlk_event *ev)
 {
 	assert(st);

--- a/libmlk-core/mlk/core/action-stack.h	Sat Mar 04 14:23:59 2023 +0100
+++ b/libmlk-core/mlk/core/action-stack.h	Sat Mar 04 14:42:03 2023 +0100
@@ -53,7 +53,7 @@
 	/**
 	 * (read-write)
 	 *
-	 * Number of actions in array ::mlk_action_script::actions
+	 * Number of actions in array ::mlk_action_stack::actions
 	 *
 	 * \warning changing this value must be kept in sync with the array
 	 *          dimension.
@@ -66,7 +66,7 @@
 #endif
 
 /**
- * Initialize the action sequence structure.
+ * Initialize the action stack structure.
  *
  * This function will set all pointers in the ::mlk_action_stack::actions to
  * NULL.
@@ -129,6 +129,7 @@
  * \pre stack != NULL
  * \param stack the action stack
  * \param ticks frame ticks
+ * \return non-zero if completed
  */
 int
 mlk_action_stack_update(struct mlk_action_stack *stack,
@@ -144,6 +145,7 @@
 mlk_action_stack_draw(const struct mlk_action_stack *stack);
 
 /**
+ * Invoke ::mlk_action_finish on all actions left.
  *
  * \pre stack != NULL
  * \param stack the action stack

--- a/libmlk-core/mlk/core/drawable-stack.c	Sat Mar 04 14:23:59 2023 +0100
+++ b/libmlk-core/mlk/core/drawable-stack.c	Sat Mar 04 14:42:03 2023 +0100
@@ -1,5 +1,5 @@
 /*
- * drawable-stack.c -- convenient stack of drawables
+ * drawable-stack.c -- convenient stack of drawable objects
  *
  * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
  *
@@ -52,6 +52,20 @@
 }
 
 int
+mlk_drawable_stack_completed(const struct mlk_drawable_stack *st)
+{
+	assert(st);
+
+	struct mlk_drawable *dw;
+
+	DRAWABLE_FOREACH(st, dw)
+		if (dw)
+			return 0;
+
+	return 1;
+}
+
+int
 mlk_drawable_stack_update(struct mlk_drawable_stack *st, unsigned int ticks)
 {
 	assert(st);
@@ -87,20 +101,6 @@
 			mlk_drawable_draw(dw);
 }
 
-int
-mlk_drawable_stack_completed(const struct mlk_drawable_stack *st)
-{
-	assert(st);
-
-	struct mlk_drawable *dw;
-
-	DRAWABLE_FOREACH(st, dw)
-		if (dw)
-			return 0;
-
-	return 1;
-}
-
 void
 mlk_drawable_stack_finish(struct mlk_drawable_stack *st)
 {

--- a/libmlk-core/mlk/core/drawable-stack.h	Sat Mar 04 14:23:59 2023 +0100
+++ b/libmlk-core/mlk/core/drawable-stack.h	Sat Mar 04 14:42:03 2023 +0100
@@ -1,5 +1,5 @@
 /*
- * drawable-stack.h -- convenient stack of drawables
+ * drawable-stack.h -- convenient stack of drawable objects
  *
  * Copyright (c) 2020-2023 David Demelier <markand@malikania.fr>
  *
@@ -19,10 +19,33 @@
 #ifndef MLK_CORE_DRAWABLE_STACK_H
 #define MLK_CORE_DRAWABLE_STACK_H
 
+/**
+ * \file mlk/core/drawable-stack.h
+ * \brief Convenient stack of drawable objects
+ */
+
 #include <stddef.h>
 
+/**
+ * \struct mlk_drawable_stack
+ * \brief Drawable stack structure
+ */
 struct mlk_drawable_stack {
+	/**
+	 * (read-write, borrowed)
+	 *
+	 * Array of non-owning drawables to draw.
+	 */
 	struct mlk_drawable **objects;
+
+	/**
+	 * (read-write)
+	 *
+	 * Number of drawables in array ::mlk_drawable_stack::objects.
+	 *
+	 * \warning changing this value must be kept in sync with the array
+	 *          dimension.
+	 */
 	size_t objectsz;
 };
 
@@ -30,23 +53,70 @@
 extern "C" {
 #endif
 
+/**
+ * Initialize the drawable stack.
+ *
+ * This function will set all pointers in the ::mlk_drawable_stack::objects to
+ * NULL.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ */
 void
-mlk_drawable_stack_init(struct mlk_drawable_stack *);
+mlk_drawable_stack_init(struct mlk_drawable_stack *stack);
 
+/**
+ * Try to append a new drawable into the stack if one slot in the
+ * ::mlk_drawable_stack::objects is NULL
+ *
+ * The object is inserted as-is and ownership is left to the caller.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ * \param drawable the object to append
+ * \return 0 on success or ::MLK_ERR_NO_MEM if full.
+ */
 int
-mlk_drawable_stack_add(struct mlk_drawable_stack *, struct mlk_drawable *);
-
-int
-mlk_drawable_stack_update(struct mlk_drawable_stack *, unsigned int);
+mlk_drawable_stack_add(struct mlk_drawable_stack *stack,
+                       struct mlk_drawable *drawable);
 
-void
-mlk_drawable_stack_draw(struct mlk_drawable_stack *);
+/**
+ * Tells if there are still at least one drawable in the stack.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ */
+int
+mlk_drawable_stack_completed(const struct mlk_drawable_stack *stack);
 
+/**
+ * Invoke ::mlk_draw_update on all drawables.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ * \param ticks frame ticks
+ * \return non-zero if completed
+ */
 int
-mlk_drawable_stack_completed(const struct mlk_drawable_stack *);
+mlk_drawable_stack_update(struct mlk_drawable_stack *stack, unsigned int ticks);
 
+/**
+ * Invoke ::mlk_draw_update on all drawables.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ */
 void
-mlk_drawable_stack_finish(struct mlk_drawable_stack *);
+mlk_drawable_stack_draw(struct mlk_drawable_stack *stack);
+
+/**
+ * Invoke ::mlk_draw_finish on all drawables left.
+ *
+ * \pre stack != NULL
+ * \param stack the drawable stack
+ */
+void
+mlk_drawable_stack_finish(struct mlk_drawable_stack *stack);
 
 #if defined(__cplusplus)
 }