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