# HG changeset patch # User David Demelier # Date 1580130829 -3600 # Node ID 53b217afe122fd856a46e428747aae197ce7352a # Parent 5da49274e5fb27a2c2be8bc855e25c13733664a0 doc: improve doxygen documentation diff -r 5da49274e5fb -r 53b217afe122 src/core/action.h --- 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 diff -r 5da49274e5fb -r 53b217afe122 src/core/message.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 @@ -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 */ diff -r 5da49274e5fb -r 53b217afe122 src/core/script.h --- 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 @@ -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 diff -r 5da49274e5fb -r 53b217afe122 src/core/util.h --- 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 /** @@ -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. diff -r 5da49274e5fb -r 53b217afe122 src/core/wait.h --- 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 @@ -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