--- a/src/core/action.h	Mon Jan 27 13:31:24 2020 +0100
+++ b/src/core/action.h	Mon Jan 27 14:13:49 2020 +0100
@@ -22,6 +22,12 @@
 /**
  * \file action.h
  * \brief Action states.
+ * \ingroup actions
+ */
+
+/**
+ * \defgroup actions Actions
+ * \brief Predefined actions.
  */
 
 #include <stdbool.h>

--- a/src/core/message.h	Mon Jan 27 13:31:24 2020 +0100
+++ b/src/core/message.h	Mon Jan 27 14:13:49 2020 +0100
@@ -22,6 +22,44 @@
 /**
  * \file message.h
  * \brief Message dialog.
+ * \ingroup actions
+ *
+ * This module's purpose is to show a dialog box into the screen to show text
+ * and optionally ask the user a question.
+ *
+ * By itself, it is very low level and does not prevent other parts of the game
+ * to use the input so you probably need to inhibit input if your dialog is
+ * meant to be displayed on a map.
+ *
+ * To use it use the following procedure:
+ *
+ * 1. Create a struct message object and set required properties,
+ * 2. Call \ref message_start to reset the state,
+ * 3. Call \ref message_handle and \ref message_update with appropriate values,
+ * 4. Call \ref message_draw to render the dialog.
+ *
+ * Depending on message flags or user input, step 3 may return true in this
+ * case you should stop using the message as it has completed rendering.
+ *
+ * \note All properties must exist until the object is no longer used.
+ *
+ * \code
+ * struct message msg = {
+ * 	// You can show up to 6 lines.
+ * 	.text = {
+ * 		"Hello, what's up?"
+ * 	},
+ * 	// This image will be shown on the left as user face.
+ * 	.avatar = mysuperavatar,
+ * 	// This should point to a image that is used as background.
+ * 	.frame = mysuperframe,
+ * 	// The first color is normal text, the second is for selected text
+ * 	// in case of question.
+ * 	.colors = { 0xffffffff, 0x0000ffff },
+ * 	// This indicates this message is a question.
+ * 	.flags = MESSAGE_QUESTION
+ * };
+ * \endcode
  */
 
 #include <stdbool.h>
@@ -59,7 +97,7 @@
 struct message {
 	const char *text[6];            /*!< (RW) Lines of text to show */
 	struct texture *frame;          /*!< (RW) Frame to use */
-	struct texture *avatar;         /*!< (RW) Optional avatar */
+	struct texture *avatar;         /*!< (RW) Avatar face (optional) */
 	struct font *font;              /*!< (RW) Font to use */
 	unsigned long colors[2];        /*!< (RW) Normal/selected colors */
 	unsigned int index;             /*!< (RW) Line selected */

--- a/src/core/script.h	Mon Jan 27 13:31:24 2020 +0100
+++ b/src/core/script.h	Mon Jan 27 14:13:49 2020 +0100
@@ -22,6 +22,7 @@
 /**
  * \file script.h
  * \brief Convenient sequence of actions.
+ * \ingroup actions
  *
  * Those routines wrap individual actions into a sequence of actions into an
  * action itself.
@@ -31,10 +32,12 @@
  *
  * In a nutshell, to write a scenario you should:
  *
- * 1. Create a script with see script_init,
- * 2. Create one or more actions and append with script_append,
- * 3. Start the action using script_start,
- * 4. Put the script into the game using game_add_action.
+ * 1. Create a script with see \ref script_init,
+ * 2. Create one or more actions and append with \ref script_append,
+ * 3. Start the action using \ref script_start,
+ * 4. Put the script into the game using \ref game_add_action.
+ *
+ * \warning You must always call \ref script_init before using this object.
  */
 
 #include <stdbool.h>
@@ -133,6 +136,9 @@
 /**
  * Create an action from the script for use into the game.
  *
+ * This function is meant to transform the script into an action itself and be
+ * added to the game using \ref game_add_action.
+ *
  * \pre s != NULL
  * \pre dst != NULL
  * \param s the script

--- a/src/core/util.h	Mon Jan 27 13:31:24 2020 +0100
+++ b/src/core/util.h	Mon Jan 27 14:13:49 2020 +0100
@@ -19,6 +19,16 @@
 #ifndef MOLKO_UTIL_H
 #define MOLKO_UTIL_H
 
+/**
+ * \file util.h
+ * \brief Utilities.
+ *
+ * This file contains several utilities.
+ *
+ * \note In contrast to other files, identifiers are not prefixed with `util_`
+ *       for convenience.
+ */
+
 #include <stddef.h>
 
 /**
@@ -27,7 +37,7 @@
  * \param x the array
  * \return the number of elements
  */
-#define nelem(x) sizeof ((x)) / sizeof ((x)[0])
+#define NELEM(x) sizeof ((x)) / sizeof ((x)[0])
 
 /**
  * Wrapper around malloc(3) that exits on allocation failure.

--- a/src/core/wait.h	Mon Jan 27 13:31:24 2020 +0100
+++ b/src/core/wait.h	Mon Jan 27 14:13:49 2020 +0100
@@ -22,6 +22,30 @@
 /**
  * \file wait.h
  * \brief Wait action.
+ * \ingroup actions
+ *
+ * This module is meant to create a delayed action.
+ *
+ * Combined with \ref script.h, you can create a sequence of actions with
+ * delays between each.
+ *
+ * \code
+ * struct script script;
+ * struct action action;
+ *
+ * // Prepare the script.
+ * script_init(&script);
+ *
+ * // Add some actions to script using script_append.
+ * // ...
+ *
+ * // Wait one second delay before next action.
+ * wait_action(&(struct wait) { .delay = 1000 }, &action);
+ * script_append(&script, &action);
+ *
+ * // Add more actions after this delay.
+ * // ...
+ * \endcode
  */
 
 #include <stdbool.h>
@@ -32,14 +56,14 @@
  * \brief Wait action.
  */
 struct wait {
-	unsigned int delay;             /*!< (RW) Time to wait */
+	unsigned int delay;             /*!< (RW) Time to wait in milliseconds */
 	unsigned int elapsed;           /*!< (RO) Elapsed time */
 };
 
 /**
  * Start the wait action.
  *
- * This function is equivalent to w->elapsed = 0;
+ * This function is equivalent to `w->elapsed = 0`;
  *
  * \pre w != NULL
  * \param w the wait object