--- a/libmlk-core/mlk/core/drawable-stack.h	Sat Mar 04 14:42:03 2023 +0100
+++ b/libmlk-core/mlk/core/drawable-stack.h	Sat Mar 04 14:53:18 2023 +0100
@@ -90,7 +90,7 @@
 mlk_drawable_stack_completed(const struct mlk_drawable_stack *stack);
 
 /**
- * Invoke ::mlk_draw_update on all drawables.
+ * Invoke ::mlk_drawable_update on all drawables.
  *
  * \pre stack != NULL
  * \param stack the drawable stack
@@ -101,7 +101,7 @@
 mlk_drawable_stack_update(struct mlk_drawable_stack *stack, unsigned int ticks);
 
 /**
- * Invoke ::mlk_draw_update on all drawables.
+ * Invoke ::mlk_drawable_update on all drawables.
  *
  * \pre stack != NULL
  * \param stack the drawable stack
@@ -110,7 +110,7 @@
 mlk_drawable_stack_draw(struct mlk_drawable_stack *stack);
 
 /**
- * Invoke ::mlk_draw_finish on all drawables left.
+ * Invoke ::mlk_drawable_finish on all drawables left.
  *
  * \pre stack != NULL
  * \param stack the drawable stack

--- a/libmlk-core/mlk/core/drawable.h	Sat Mar 04 14:42:03 2023 +0100
+++ b/libmlk-core/mlk/core/drawable.h	Sat Mar 04 14:53:18 2023 +0100
@@ -19,31 +19,121 @@
 #ifndef MLK_CORE_DRAWABLE_H
 #define MLK_CORE_DRAWABLE_H
 
+/**
+ * \file mlk/core/drawable.h
+ * \brief Automatic drawable objects
+ */
+
+/**
+ * \struct mlk_drawable
+ * \brief Drawable structure
+ */
 struct mlk_drawable {
+	/**
+	 * (read-write, borrowed, optional)
+	 *
+	 * Arbitrary user data.
+	 */
 	void *data;
+
+	/**
+	 * (read-write)
+	 *
+	 * Position in x.
+	 */
 	int x;
+
+	/**
+	 * (read-write)
+	 *
+	 * Position in y.
+	 */
 	int y;
-	int (*update)(struct mlk_drawable *, unsigned int);
-	void (*draw)(struct mlk_drawable *);
-	void (*end)(struct mlk_drawable *);
-	void (*finish)(struct mlk_drawable *);
+
+	/**
+	 * (optional)
+	 *
+	 * Update the drawable with the given ticks since last frame.
+	 *
+	 * The callback should return non-zero if it is considered complete.
+	 *
+	 * \param self this drawable
+	 * \param ticks frame ticks
+	 * \return non-zero if complete
+	 */
+	int (*update)(struct mlk_drawable *self, unsigned int ticks);
+
+	/**
+	 * (optional)
+	 *
+	 * Draw the drawable.
+	 *
+	 * \param self this drawable
+	 */
+	void (*draw)(struct mlk_drawable *self);
+
+	/**
+	 * (optional)
+	 *
+	 * Terminate the drawable.
+	 *
+	 * In contrast to finish, this function should be called after the
+	 * drawable was considered complete.
+	 *
+	 * \param self this drawable
+	 */
+	void (*end)(struct mlk_drawable *self);
+
+	/**
+	 * (optional)
+	 *
+	 * Dispose resources allocated by/for the drawable.
+	 *
+	 * \param self this drawable
+	 */
+	void (*finish)(struct mlk_drawable *self);
 };
 
 #if defined(__cplusplus)
 extern "C" {
 #endif
 
+/**
+ * Invoke ::mlk_drawable::update function if not null.
+ *
+ * \pre drawable != NULL
+ * \param drawable the drawable
+ * \param ticks frame ticks
+ */
 int
-mlk_drawable_update(struct mlk_drawable *, unsigned int);
-
-void
-mlk_drawable_draw(struct mlk_drawable *);
+mlk_drawable_update(struct mlk_drawable *drawable, unsigned int ticks);
 
+/**
+ * Invoke ::mlk_drawable::draw function if not null.
+ *
+ * \pre drawable != NULL
+ * \param drawable the drawable
+ */
 void
-mlk_drawable_end(struct mlk_drawable *);
+mlk_drawable_draw(struct mlk_drawable *drawable);
 
+/**
+ * Invoke ::mlk_drawable::end function if not null.
+ *
+ * \pre drawable != NULL
+ * \param drawable the drawable
+ */
 void
-mlk_drawable_finish(struct mlk_drawable *);
+mlk_drawable_end(struct mlk_drawable *drawable);
+
+/**
+ * Invoke ::mlk_drawable::finish function if not null.
+ *
+ * \pre drawable != NULL
+ * \param drawable the drawable
+ */
+void
+mlk_drawable_finish(struct mlk_drawable *drawable);
 
 #if defined(__cplusplus)
 }