Mercurial > molko
changeset 147:b386d25832c8
doc: use new nomenclature, closes #2497
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Thu, 15 Oct 2020 09:21:04 +0200 |
| parents | 7d7ea7a9cf50 |
| children | c577c15df07f |
| files | doxygen/mainpage.c doxygen/page-howto-initialization.c libadventure/adventure/splashscreen_state.h libadventure/adventure/trace_hud.h libcore/core/action.h libcore/core/animation.h libcore/core/button.h libcore/core/checkbox.h libcore/core/clock.h libcore/core/debug.h libcore/core/drawable.h libcore/core/event.h libcore/core/font.h libcore/core/frame.h libcore/core/game.c libcore/core/game.h libcore/core/inventory.h libcore/core/inventory_dialog.h libcore/core/item.h libcore/core/label.h libcore/core/map.h libcore/core/map_state.h libcore/core/message.h libcore/core/rbuf.h libcore/core/script.h libcore/core/sound.h libcore/core/sprite.h libcore/core/state.h libcore/core/texture.h libcore/core/theme.h libcore/core/wait.h libcore/core/walksprite.h libcore/core/window.h |
| diffstat | 33 files changed, 216 insertions(+), 334 deletions(-) [+] |
line wrap: on
line diff
--- a/doxygen/mainpage.c Wed Oct 14 18:20:58 2020 +0200 +++ b/doxygen/mainpage.c Thu Oct 15 09:21:04 2020 +0200 @@ -51,7 +51,7 @@ * with _p.h are usually reserved for the implementation and should not be used * unless you know what you're doing. * - * # Documentation convention + * # Documentation nomenclature * * Every modules are organized per files and referenced this way. For example, * if you need to access the error handling, you just have to use \ref error.h @@ -60,11 +60,39 @@ * ## Structures * * Almost every structure are exposed directly to the user and allocated on the - * stack. Each member is documented with the following prefix: + * stack. Each member is documented with the following prefix format (XYZ) + * where: + * + * The letter *X* defines the following restriction + * + * - `+`: The property is readable/editable by the user, + * - `-`: The property is readable by the user, + * - `*`: The property is not meant to be used directly by the user. + * + * The letter *Y* can be set to `&` in that case means it is only referenced + * and is not an owned property (usually a non-owning pointer). Which means + * user is responsible for deallocation if required. + * + * The finall letter *Z* can be set to `?` which means it is optional (like a + * nullable pointer). * - * - `(RW)`: The property is readable/editable by the user, - * - `(RO)`: The property is readable by the user, - * - `(PV)`: The property is not meant to be used directly by the user. + * Examples: + * + * ```c + * struct foo { + * int x; // (+) Position in x. + * int y; // (+) Position in y. + * struct theme *th; // (+&?) Theme to use. + * unsigned int elapsed; // (-) Elapsed time since last frame. + * struct texture text; // (*) Texture used for rendering. + * }; + * ``` + * + * Within this structure, the fields `x` and `y` are completely accessible to + * the user for both reading/writing. The field `th` is an optional non-owning + * pointer to a theme which is also readable/writable. The field `elapsed` is + * readable but should not be modified. Finally, the field `text` is private + * and should not be touched by the user. * * ## Functions * @@ -115,7 +143,7 @@ * ## Modules * * Whenever possible, functions that needs a structure context will always take - * it as first argument. Opaque structures may be returned by pointers instead. + * it as first argument. * * This let the user to control lifetime and allocation storage for most of the * API objects. @@ -129,21 +157,13 @@ * clock_elapsed(&clock); * \endcode * - * Example (opaque object): - * - * \code - * struct texture *tex; - * - * tex = image_openf("foo.png"); - * \endcode - * * ## Thread safety and reentrancy * * The core API is **not** thread-safe at all. Any module must always be used in * a single thread unless you really know what you're doing. * - * Most of the API is reentrant though except the \ref window.h and \ref error.h - * which use global objects. + * Most of the API is reentrant though except the some modules which use global + * objects. * * \note This may change in the future. * @@ -152,13 +172,4 @@ * Functions that may fail usually return a boolean. If an error occured, it is * stored in a global variable that are accessed through the \ref error.h * module. - * - * However, functions returning an opaque object may return NULL instead. - * - * Example: - * - * \code - * if (!sys_init()) - * error_fatalf(); // Print an error and exits. - * \endcode */
--- a/doxygen/page-howto-initialization.c Wed Oct 14 18:20:58 2020 +0200 +++ b/doxygen/page-howto-initialization.c Thu Oct 15 09:21:04 2020 +0200 @@ -19,8 +19,8 @@ * * | System | Init function | Close function | Remarks | * |---------|------------------|--------------------|------------------------| - * | General | sys_init | sys_finish | Required for most API | - * | Window | window_init | window_finish | Required by some parts | + * | General | sys_init | sys_finish | Required for most API | + * | Window | window_init | window_finish | Required by some parts | * * All init functions set an error code if any and you're encouraged to test the * result and check the error if any.
--- a/libadventure/adventure/splashscreen_state.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libadventure/adventure/splashscreen_state.h Thu Oct 15 09:21:04 2020 +0200 @@ -30,11 +30,11 @@ * \brief Data for splashscreen. */ extern struct splashscreen_state_data { - struct texture text; /*!< (RW) Texture for the text. */ - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int elapsed; /*!< (RW) Time elapsed. */ -} splashscreen_state_data; /*!< (RW) Global state data. */ + struct texture text; /*!< (+) Texture for the text. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int elapsed; /*!< (+) Time elapsed. */ +} splashscreen_state_data; /*!< (+) Global state data. */ /** * \brief Splash screen state.
--- a/libadventure/adventure/trace_hud.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libadventure/adventure/trace_hud.h Thu Oct 15 09:21:04 2020 +0200 @@ -35,8 +35,8 @@ * \brief Trace HUD options. */ struct trace_hud { - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ - unsigned int timeout; /*!< (RW) Timeout to remove messages. */ + struct theme *theme; /*!< (+&?) Theme to use. */ + unsigned int timeout; /*!< (+) Timeout to remove messages. */ }; /**
--- a/libcore/core/action.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/action.h Thu Oct 15 09:21:04 2020 +0200 @@ -48,16 +48,12 @@ */ struct action { /** - * (RW, optional) - * - * Arbitrary user data. + * (+&?) Arbitrary user data. */ void *data; /** - * (RW, optional) - * - * Handle event. + * (+&?) Handle event. * * \param act this action * \param ev the event @@ -65,9 +61,7 @@ void (*handle)(struct action *act, const union event *ev); /** - * (RW, optional) - * - * Update the action. + * (+?) Update the action. * * \param act this action * \param ticks the number of milliseconds since last frame @@ -76,18 +70,14 @@ bool (*update)(struct action *act, unsigned int ticks); /** - * (RW) - * - * Draw the action. + * (+?) Draw the action. * * \param act this action */ void (*draw)(struct action *act); /** - * (RW) - * - * Called when the action was completed. + * (+?) Called when the action was completed. * * This callback is mostly provided to allow the user doing something * else once an action is complete. Predefined actions should not use @@ -98,7 +88,7 @@ void (*end)(struct action *act); /** - * (RW) + * (+?) Destroy internal resources. * * Close the action before removal. This function should be used to * deallocate memory if necessary. @@ -168,7 +158,7 @@ * from the heap. */ struct action_stack { - struct action *actions[ACTION_STACK_MAX]; /*!< (RW) Actions */ + struct action *actions[ACTION_STACK_MAX]; /*!< (+) Actions */ }; /**
--- a/libcore/core/animation.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/animation.h Thu Oct 15 09:21:04 2020 +0200 @@ -34,11 +34,11 @@ * \brief Animation object */ struct animation { - struct sprite *sprite; /*!< (RW, ref) Sprite to use. */ - unsigned int row; /*!< (RO) Current row. */ - unsigned int column; /*!< (RO) Current column. */ - unsigned int delay; /*!< (RO) Delay between frames. */ - unsigned int elapsed; /*!< (RO) Elapsed time since last frame. */ + struct sprite *sprite; /*!< (+&) Sprite to use. */ + unsigned int row; /*!< (-) Current row. */ + unsigned int column; /*!< (-) Current column. */ + unsigned int delay; /*!< (-) Delay between frames. */ + unsigned int elapsed; /*!< (-) Elapsed time since last frame. */ }; /**
--- a/libcore/core/button.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/button.h Thu Oct 15 09:21:04 2020 +0200 @@ -41,13 +41,13 @@ * \brief GUI button. */ struct button { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int w; /*!< (RW) Width. */ - unsigned int h; /*!< (RW) Height. */ - const char *text; /*!< (RW, ref) Text to draw. */ - enum button_state state; /*!< (RW) Button state. */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int w; /*!< (+) Width. */ + unsigned int h; /*!< (+) Height. */ + const char *text; /*!< (+&) Text to draw. */ + enum button_state state; /*!< (+) Button state. */ + struct theme *theme; /*!< (+&?) Theme to use. */ }; /**
--- a/libcore/core/checkbox.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/checkbox.h Thu Oct 15 09:21:04 2020 +0200 @@ -32,13 +32,13 @@ * \brief GUI checkbox. */ struct checkbox { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int w; /*!< (RW) Width. */ - unsigned int h; /*!< (RW) Height. */ - const char *label; /*!< (RW, ref) Text to show. */ - bool checked; /*!< (RW) Is activated? */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int w; /*!< (+) Width. */ + unsigned int h; /*!< (+) Height. */ + const char *label; /*!< (+&) Text to show. */ + bool checked; /*!< (+) Is activated? */ + struct theme *theme; /*!< (+&?) Theme to use. */ }; /**
--- a/libcore/core/clock.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/clock.h Thu Oct 15 09:21:04 2020 +0200 @@ -29,7 +29,7 @@ * \brief Clock structure. */ struct clock { - unsigned int ticks; /*!< time point on initialization */ + unsigned int ticks; /*!< (-) Time point on initialization. */ }; /**
--- a/libcore/core/debug.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/debug.h Thu Oct 15 09:21:04 2020 +0200 @@ -79,7 +79,7 @@ * in core API. */ struct debug_options { - bool enable; /*!< (RW) Enable core API debugging. */ + bool enable; /*!< (+) Enable core API debugging. */ }; /** @@ -88,9 +88,9 @@ * Use this structure each time you need to print one or more messages. */ struct debug_report { - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ - unsigned long color; /*!< (RW) Font foreground color to use. */ - unsigned int count; /*!< (PV) Number of messages already printed. */ + struct theme *theme; /*!< (+&?) Theme to use. */ + unsigned long color; /*!< (+) Font foreground color to use. */ + unsigned int count; /*!< (-) Number of messages already printed. */ }; /**
--- a/libcore/core/drawable.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/drawable.h Thu Oct 15 09:21:04 2020 +0200 @@ -37,12 +37,12 @@ * This structure is used to */ struct drawable { - void *data; /*!< (RW) Drawable data. */ - int x; /*!< (RW) X coordinate if necessary. */ - int y; /*!< (RW) Y coordinate if necessary. */ + void *data; /*!< (+&?) Drawable data. */ + int x; /*!< (+) X coordinate if necessary. */ + int y; /*!< (+) Y coordinate if necessary. */ /** - * Update this drawable. + * (+?) Update this drawable. * * \param dw the drawable object * \param ticks the number of ticks since last frame @@ -51,23 +51,21 @@ bool (*update)(struct drawable *dw, unsigned int ticks); /** - * Draw this drawable. + * (+?) Draw this drawable. * * \param dw the drawable object */ void (*draw)(struct drawable *dw); /** - * (RW) - * - * Called immediately after the drawable ended. + * (+?) Called when drawable finished. * * \param act this action */ void (*end)(struct drawable *act); /** - * Destroy the drawable if necessary. + * (+?) Destroy the drawable if necessary. * * \note This function is optional and can be NULL. * \param dw the drawable object @@ -122,7 +120,7 @@ * You can add, clear, update and draw them. */ struct drawable_stack { - struct drawable *objects[DRAWABLE_STACK_MAX]; /*!< (RW) Drawables. */ + struct drawable *objects[DRAWABLE_STACK_MAX]; /*!< (+&?) Drawables. */ }; /**
--- a/libcore/core/event.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/event.h Thu Oct 15 09:21:04 2020 +0200 @@ -46,38 +46,38 @@ * \brief Key event. */ struct event_key { - enum event_type type; /*!< EVENT_KEYDOWN or EVENT_KEYUP */ - enum key key; /*!< Which key */ + enum event_type type; /*!< (+) EVENT_KEYDOWN or EVENT_KEYUP */ + enum key key; /*!< (+) Which key */ }; /** * \brief Mouse motion event. */ struct event_mouse { - enum event_type type; /*!< EVENT_MOUSE */ - enum mouse_button buttons; /*!< OR'ed buttons that are pressed */ - int x; /*!< Mouse position in x */ - int y; /*!< Mouse position in y */ + enum event_type type; /*!< (+) EVENT_MOUSE */ + enum mouse_button buttons; /*!< (+) OR'ed buttons that are pressed */ + int x; /*!< (+) Mouse position in x */ + int y; /*!< (+) Mouse position in y */ }; /** * \brief Mouse click event. */ struct event_click { - enum event_type type; /*!< EVENT_CLICKDOWN or EVENT_CLICKUP */ - enum mouse_button button; /*!< Unique button that was pressed */ - int x; /*!< Mouse position in x */ - int y; /*!< Mouse position in y */ + enum event_type type; /*!< (+) EVENT_CLICKDOWN or EVENT_CLICKUP */ + enum mouse_button button; /*!< (+) Unique button that was pressed */ + int x; /*!< (+) Mouse position in x */ + int y; /*!< (+) Mouse position in y */ }; /** * \brief Store events. */ union event { - enum event_type type; /*!< Which kind of event */ - struct event_key key; /*!< Key event */ - struct event_mouse mouse; /*!< Mouse motion event */ - struct event_click click; /*!< Mouse click event */ + enum event_type type; /*!< (+) Which kind of event */ + struct event_key key; /*!< (+) Key event */ + struct event_mouse mouse; /*!< (+) Mouse motion event */ + struct event_click click; /*!< (+) Mouse click event */ }; /**
--- a/libcore/core/font.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/font.h Thu Oct 15 09:21:04 2020 +0200 @@ -42,9 +42,9 @@ * \brief Font object. */ struct font { - enum font_style style; /*!< (RW) Style for rendering. */ - unsigned long color; /*!< (RW) Color for rendering. */ - void *handle; /*!< (PV) Native handle. */ + enum font_style style; /*!< (+) Style for rendering. */ + unsigned long color; /*!< (+) Color for rendering. */ + void *handle; /*!< (*) Native handle. */ }; /**
--- a/libcore/core/frame.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/frame.h Thu Oct 15 09:21:04 2020 +0200 @@ -38,12 +38,12 @@ * \brief GUI frame. */ struct frame { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int w; /*!< (RW) Width. */ - unsigned int h; /*!< (RW) Height. */ - enum frame_style style; /*!< (RW) Frame style. */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int w; /*!< (+) Width. */ + unsigned int h; /*!< (+) Height. */ + enum frame_style style; /*!< (+) Frame style. */ + struct theme *theme; /*!< (+&?) Theme to use. */ }; /**
--- a/libcore/core/game.c Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/game.c Thu Oct 15 09:21:04 2020 +0200 @@ -26,72 +26,6 @@ struct game game; -#if 0 - -static struct action * -find_empty_action(void) -{ - static struct action null; - - for (struct action *a = game.actions; a != &game.actions[GAME_ACTIONS_MAX]; ++a) - if (memcmp(a, &null, sizeof (struct action)) == 0) - return a; - - return NULL; -} - -static void -clear_actions(void) -{ - for (struct action *a = game.actions; a != &game.actions[GAME_ACTIONS_MAX]; ++a) { - /* These actions are removed on state change. */ - if (a->flags & ACTION_AUTO_LEAVE) { - if (a->finish) - a->finish(a); - - memset(a, 0, sizeof (struct action)); - } - } -} - -static void -handle_actions(const union event *event) -{ - for (struct action *a = game.actions; a != &game.actions[GAME_ACTIONS_MAX]; ++a) - if (a->handle) - a->handle(a, event); -} - -static void -update_actions(unsigned int ticks) -{ - for (size_t i = 0; i < GAME_ACTIONS_MAX; ++i) { - struct action *a = &game.actions[i]; - - if (!a->update) - continue; - - if (a->update(a, ticks)) { - if (a->end) - a->end(a); - if (a->finish) - a->finish(a); - - memset(&game.actions[i], 0, sizeof (struct action)); - } - } -} - -static void -draw_actions(void) -{ - for (size_t i = 0; i < GAME_ACTIONS_MAX; ++i) - if (game.actions[i].draw) - game.actions[i].draw(&game.actions[i]); -} - -#endif - void game_switch(struct state *state, bool quick) { @@ -112,10 +46,6 @@ if (game.state && !(game.inhibit & INHIBIT_STATE_INPUT)) game.state->handle(event); - -#if 0 - handle_actions(event); -#endif } void @@ -131,20 +61,11 @@ game.state = game.state_next; game.state->enter(); game.state_next = NULL; - -#if 0 - /* Remove any actions that must be deleted. */ - clear_actions(); -#endif } if (game.state) game.state->update(ticks); } - -#if 0 - update_actions(ticks); -#endif } void @@ -153,25 +74,9 @@ if (game.state && !(game.inhibit & INHIBIT_STATE_DRAW)) game.state->draw(); -#if 0 - draw_actions(); -#endif painter_present(); } -#if 0 -void -game_add_action(const struct action *action) -{ - assert(action); - - struct action *pos; - - if ((pos = find_empty_action())) - memcpy(pos, action, sizeof (struct action)); -} -#endif - void game_quit(void) {
--- a/libcore/core/game.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/game.h Thu Oct 15 09:21:04 2020 +0200 @@ -26,7 +26,6 @@ #include <stdbool.h> -#include "action.h" #include "inhibit.h" /** @@ -43,14 +42,11 @@ */ struct game { /* Inhibition */ - enum inhibit inhibit; /*!< (RW) What to disable. */ + enum inhibit inhibit; /*!< (+) What to disable. */ /* Game states. */ - struct state *state; /*!< (RO) Current state */ - struct state *state_next; /*!< (RO) Next state */ - - /** Array of actions. */ - struct action actions[GAME_ACTIONS_MAX]; + struct state *state; /*!< (-) Current state */ + struct state *state_next; /*!< (-) Next state */ }; /** @@ -94,19 +90,6 @@ game_draw(void); /** - * Add an action to the game. - * - * If there are no room for the action, action is discarded. Make sure to not - * exceed the limit GAME_ACTIONS_MAX. - * - * \pre action != NULL - * \param action the action to copy - * \note The core API **never** add actions by itself. - */ -void -game_add_action(const struct action *action); - -/** * Stop the game. * * This will effectively stop the current state but the main loop may continue
--- a/libcore/core/inventory.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/inventory.h Thu Oct 15 09:21:04 2020 +0200 @@ -43,8 +43,8 @@ * and has a given amount of it. */ struct inventory_slot { - struct item *item; /*!< (RO, ref) Pointer to the item. */ - unsigned int amount; /*!< (RO) Number of items in this slot. */ + struct item *item; /*!< (+&?) Pointer to the item. */ + unsigned int amount; /*!< (-) Number of items in this slot. */ }; /** @@ -52,9 +52,7 @@ */ struct inventory { /** - * (RW) - * - * Grid of objects. + * (-) Grid of objects. */ struct inventory_slot items[INVENTORY_ROWS_MAX][INVENTORY_COLS_MAX]; };
--- a/libcore/core/inventory_dialog.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/inventory_dialog.h Thu Oct 15 09:21:04 2020 +0200 @@ -40,19 +40,19 @@ * \brief Inventory dialog. */ struct inventory_dialog { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - struct inventory *inv; /*!< (RW, ref) Inventory to use. */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ - struct button bsort; /*!< (RO) Button sort. */ - struct frame fgrid; /*!< (RO) Grid frame. */ - struct frame fname; /*!< (RO) Frame for name. */ - struct frame fdesc; /*!< (RO) Frame for description. */ - struct label lname; /*!< (RO) Label for name. */ - struct label ldesc; /*!< (RO) Label for description. */ - enum inventory_dialog_state state; /*!< (RO) Current dialog state. */ - unsigned int selrow; /*!< (RO) Current selected row. */ - unsigned int selcol; /*!< (RO) Current selected column. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + struct inventory *inv; /*!< (+&) Inventory to use. */ + struct theme *theme; /*!< (+&?) Theme to use. */ + struct button bsort; /*!< (-) Button sort. */ + struct frame fgrid; /*!< (-) Grid frame. */ + struct frame fname; /*!< (-) Frame for name. */ + struct frame fdesc; /*!< (-) Frame for description. */ + struct label lname; /*!< (-) Label for name. */ + struct label ldesc; /*!< (-) Label for description. */ + enum inventory_dialog_state state; /*!< (-) Current dialog state. */ + unsigned int selrow; /*!< (-) Current selected row. */ + unsigned int selcol; /*!< (-) Current selected column. */ }; void
--- a/libcore/core/item.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/item.h Thu Oct 15 09:21:04 2020 +0200 @@ -38,22 +38,18 @@ * \brief Inventory items. */ struct item { - const char *name; /*!< (RW) Name of item. */ - const char *summary; /*!< (RW) Summary description. */ - struct texture *icon; /*!< (RW, ref) Icon to show. */ - unsigned int stackable; /*!< (RW) Stack count allowed. */ + const char *name; /*!< (+) Name of item. */ + const char *summary; /*!< (+) Summary description. */ + struct texture *icon; /*!< (+&) Icon to show. */ + unsigned int stackable; /*!< (+) Stack count allowed. */ /** - * (RW) - * - * Execute the action for this character. + * (+) Execute the action for this character. */ void (*exec)(const struct item *, struct character *); /** - * (RW, optional) - * - * Tells if the item can be used in this context. + * (+?) Tells if the item can be used in this context. */ bool (*allowed)(const struct item *, const struct character *); };
--- a/libcore/core/label.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/label.h Thu Oct 15 09:21:04 2020 +0200 @@ -65,14 +65,14 @@ * \brief GUI label. */ struct label { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int w; /*!< (RW) Width. */ - unsigned int h; /*!< (RW) Height. */ - const char *text; /*!< (RW, ref) Text to show. */ - enum label_flags flags; /*!< (RW) Optional flags. */ - enum label_align align; /*!< (RW) How to positionate label. */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int w; /*!< (+) Width. */ + unsigned int h; /*!< (+) Height. */ + const char *text; /*!< (+&) Text to show. */ + enum label_flags flags; /*!< (+) Optional flags. */ + enum label_align align; /*!< (+) How to positionate label. */ + struct theme *theme; /*!< (+&?) Theme to use. */ }; /**
--- a/libcore/core/map.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/map.h Thu Oct 15 09:21:04 2020 +0200 @@ -43,7 +43,7 @@ * \brief Map layer. */ struct map_layer { - unsigned short *tiles; /*!< (RO) Array of tiles, depending on the map size. */ + unsigned short *tiles; /*!< (+) Array of tiles, depending on the map size. */ }; /** @@ -53,17 +53,17 @@ * logic and is left for game state. */ struct map_data { - char title[MAP_TITLE_MAX]; /*!< (RW) The map title. */ - char tileset[MAP_TILESET_MAX]; /*!< (RO) Name of tileset to use. */ - int origin_x; /*!< (RO) Where the player starts in X. */ - int origin_y; /*!< (RO) Where the player starts in Y. */ - unsigned int real_w; /*!< (RO) Real width in pixels. */ - unsigned int real_h; /*!< (RO) Real height in pixels. */ - unsigned int w; /*!< (RO) Map width in cells. */ - unsigned int h; /*!< (RO) Map height in cells. */ - unsigned short tile_w; /*!< (RO) Pixels per cell (width). */ - unsigned short tile_h; /*!< (RO) Pixels per cell (height). */ - struct map_layer layers[2]; /*!< (RO) Layers (background, foreground). */ + char title[MAP_TITLE_MAX]; /*!< (+) The map title. */ + char tileset[MAP_TILESET_MAX]; /*!< (+) Name of tileset to use. */ + int origin_x; /*!< (+) Where the player starts in X. */ + int origin_y; /*!< (+) Where the player starts in Y. */ + unsigned int real_w; /*!< (-) Real width in pixels. */ + unsigned int real_h; /*!< (-) Real height in pixels. */ + unsigned int w; /*!< (-) Map width in cells. */ + unsigned int h; /*!< (-) Map height in cells. */ + unsigned short tile_w; /*!< (-) Pixels per cell (width). */ + unsigned short tile_h; /*!< (-) Pixels per cell (height). */ + struct map_layer layers[2]; /*!< (+) Layers (background, foreground). */ }; /** @@ -72,9 +72,9 @@ * This structure reference a map and perform drawing operations. */ struct map { - struct map_data *data; /*!< (RW, ref) Map data. */ - struct texture *tileset; /*!< (RW, ref) Tileset to use. */ - struct texture picture; /*!< (RO) Map drawn into a picture. */ + struct map_data *data; /*!< (+&) Map data. */ + struct texture *tileset; /*!< (+&) Tileset to use. */ + struct texture picture; /*!< (-) Map drawn into a picture. */ }; /**
--- a/libcore/core/map_state.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/map_state.h Thu Oct 15 09:21:04 2020 +0200 @@ -38,8 +38,8 @@ * Map properties. */ struct { - struct map_data data; /*!< (RW) Map data. */ - struct map map; /*!< (RW) Map object. */ + struct map_data data; /*!< (+) Map data. */ + struct map map; /*!< (+) Map object. */ } map; /** @@ -49,20 +49,20 @@ * the view as well. */ struct { - struct sprite sprite; /*!< (RW) The sprite to use */ - int x; /*!< (RO) Player position in x */ - int y; /*!< (RO) Player position in y */ - int angle; /*!< (RO) Player angle (see walksprite) */ + struct sprite sprite; /*!< (+) The sprite to use */ + int x; /*!< (+) Player position in x */ + int y; /*!< (+) Player position in y */ + int angle; /*!< (+) Player angle (see walksprite) */ } player; /** * Position and size of the view. */ struct { - int x; /*!< (RW) Position in x */ - int y; /*!< (RW) Position in y */ - unsigned int w; /*!< (RO) View width */ - unsigned int h; /*!< (RO) View height */ + int x; /*!< (+) Position in x */ + int y; /*!< (+) Position in y */ + unsigned int w; /*!< (+) View width */ + unsigned int h; /*!< (+) View height */ } view; } map_state_data; /*!< Access to data. */
--- a/libcore/core/message.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/message.h Thu Oct 15 09:21:04 2020 +0200 @@ -110,20 +110,20 @@ * any user properties and therefore must exist while using it. */ struct message { - int x; /*!< (RW) Position in x. */ - int y; /*!< (RW) Position in y. */ - unsigned int w; /*!< (RW) Width. */ - unsigned int h; /*!< (RW) Height. */ - unsigned int delay; /*!< (RW) Delay for animations. */ - unsigned int timeout; /*!< (RW) Timeout in milliseconds. */ - const char *text[6]; /*!< (RW) Lines of text to show. */ - struct texture *avatar; /*!< (RW, ref, optional) Avatar face. */ - unsigned int index; /*!< (RW) Line selected */ - enum message_flags flags; /*!< (RW) Message flags */ - enum message_state state; /*!< (RO) Current state */ - struct theme *theme; /*!< (RW, ref, optional) Theme to use. */ - unsigned int elapsed; /*!< (RO) Time elapsed. */ - double scale; /*!< (RO) Current scale [0-1]. */ + int x; /*!< (+) Position in x. */ + int y; /*!< (+) Position in y. */ + unsigned int w; /*!< (+) Width. */ + unsigned int h; /*!< (+) Height. */ + unsigned int delay; /*!< (+) Delay for animations. */ + unsigned int timeout; /*!< (+) Timeout in milliseconds. */ + const char *text[6]; /*!< (+) Lines of text to show. */ + struct texture *avatar; /*!< (+&?) Avatar face. */ + unsigned int index; /*!< (+) Line selected */ + enum message_flags flags; /*!< (+) Message flags */ + enum message_state state; /*!< (-) Current state */ + struct theme *theme; /*!< (+&?) Theme to use. */ + unsigned int elapsed; /*!< (-) Time elapsed. */ + double scale; /*!< (-) Current scale [0-1]. */ }; /**
--- a/libcore/core/rbuf.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/rbuf.h Thu Oct 15 09:21:04 2020 +0200 @@ -31,8 +31,8 @@ * \brief Input object to store progression. */ struct rbuf { - const char *s; /*!< (RO) Pointer to current character. */ - const char *e; /*!< (RO) Pointer to end of array. */ + const char *s; /*!< (-) Pointer to current character. */ + const char *e; /*!< (-) Pointer to end of array. */ }; /**
--- a/libcore/core/script.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/script.h Thu Oct 15 09:21:04 2020 +0200 @@ -34,7 +34,6 @@ * * 1. Create a script with see \ref script_init, * 2. Create one or more actions and append with \ref script_append, - * 3. Put the script into the game using \ref game_add_action. * * \warning You must always call \ref script_init before using this object. */ @@ -59,9 +58,9 @@ * manually don't forget to adjust actionsz field accordingly. */ struct script { - struct action *actions[SCRIPT_ACTION_MAX]; /*!< (RW, ref) Array of actions. */ - size_t actionsz; /*!< (RO) Number of actions in array. */ - size_t cur; /*!< (RO) Current action index.*/ + struct action *actions[SCRIPT_ACTION_MAX]; /*!< (+&?) Array of actions. */ + size_t actionsz; /*!< (-) Number of actions in array. */ + size_t cur; /*!< (-) Current action index.*/ }; /**
--- a/libcore/core/sound.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/sound.h Thu Oct 15 09:21:04 2020 +0200 @@ -39,8 +39,8 @@ * \brief Sound chunk. */ struct sound { - enum sound_flags flags; /*!< (RW) Flags. */ - void *handle; /*!< (RO) Native handle. */ + enum sound_flags flags; /*!< (+) Flags. */ + void *handle; /*!< (*) Native handle. */ }; /**
--- a/libcore/core/sprite.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/sprite.h Thu Oct 15 09:21:04 2020 +0200 @@ -31,11 +31,11 @@ * \brief Sprite structure. */ struct sprite { - struct texture *texture; /*!< (RW) Texture to access (RO) */ - unsigned int cellw; /*!< (RW) Width per cell (RW) */ - unsigned int cellh; /*!< (RW) Height per cell (RW) */ - unsigned int nrows; /*!< (RW) Number of rows (RW) */ - unsigned int ncols; /*!< (RW) Number of columns (RW) */ + struct texture *texture; /*!< (+&) Texture to access. */ + unsigned int cellw; /*!< (-) Width per cell. */ + unsigned int cellh; /*!< (-) Height per cell. */ + unsigned int nrows; /*!< (-) Number of rows. */ + unsigned int ncols; /*!< (-) Number of columns. */ }; /**
--- a/libcore/core/state.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/state.h Thu Oct 15 09:21:04 2020 +0200 @@ -32,28 +32,30 @@ */ struct state { /** - * This function is called when the state is entered. + * (+?) This function is called when the state is entered. */ void (*enter)(void); /** - * This function is called when the state is about to be left. + * (+?) This function is called when the state is about to be left. */ void (*leave)(void); /** - * This function is called for each event that happened. + * (+) This function is called for each event that happened. */ void (*handle)(const union event *); /** + * (+) Update the state. + * * This function is called to update the game, with the number of * milliseconds since the last frame. */ void (*update)(unsigned int ticks); /** - * This function is supposed to draw the game. + * (+) This function is supposed to draw the game. */ void (*draw)(void); };
--- a/libcore/core/texture.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/texture.h Thu Oct 15 09:21:04 2020 +0200 @@ -33,9 +33,9 @@ * \brief Texture object. */ struct texture { - unsigned int w; /*!< (RO) Texture width. */ - unsigned int h; /*!< (RO) Texture height. */ - void *handle; /*!< (RO) Native handle. */ + unsigned int w; /*!< (-) Texture width. */ + unsigned int h; /*!< (-) Texture height. */ + void *handle; /*!< (*) Native handle. */ }; /**
--- a/libcore/core/theme.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/theme.h Thu Oct 15 09:21:04 2020 +0200 @@ -57,22 +57,22 @@ */ struct theme { /** - * (RW, ref) Fonts catalog. + * (+&) Fonts catalog. */ struct font *fonts[THEME_FONT_LAST]; /** - * (RW) Miscellaneous colors. + * (+) Miscellaneous colors. */ unsigned long colors[THEME_COLOR_LAST]; /** - * (RW) Padding between GUI elements. + * (+) Padding between GUI elements. */ unsigned int padding; /** - * Draw a frame. + * (+) Draw a frame. * * This function is used to draw a box usually as a container where UI * elements will be put. @@ -82,21 +82,21 @@ void (*draw_frame)(struct theme *, const struct frame *); /** - * Draw a label. + * (+) Draw a label. * * \see \ref theme_draw_label */ void (*draw_label)(struct theme *, const struct label *); /** - * Draw a button. + * (+) Draw a button. * * \see \ref theme_draw_button */ void (*draw_button)(struct theme *, const struct button *); /** - * Draw a checkbox. + * (+) Draw a checkbox. * * \see \ref theme_draw_button */
--- a/libcore/core/wait.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/wait.h Thu Oct 15 09:21:04 2020 +0200 @@ -56,8 +56,8 @@ * \brief Wait action. */ struct wait { - unsigned int delay; /*!< (RW) Time to wait in milliseconds */ - unsigned int elapsed; /*!< (RO) Elapsed time */ + unsigned int delay; /*!< (+) Time to wait in milliseconds */ + unsigned int elapsed; /*!< (-) Elapsed time */ }; /**
--- a/libcore/core/walksprite.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/walksprite.h Thu Oct 15 09:21:04 2020 +0200 @@ -58,10 +58,10 @@ * ``` */ struct walksprite { - struct sprite *sprite; /*!< (RW) The sprite to use */ - unsigned int delay; /*!< (RW) The delay between frames */ - unsigned int index; /*!< (RO) Current column index */ - unsigned int elapsed; /*!< (RO) Elapsed time since last frame */ + struct sprite *sprite; /*!< (+&) The sprite to use */ + unsigned int delay; /*!< (+) The delay between frames */ + unsigned int index; /*!< (-) Current column index */ + unsigned int elapsed; /*!< (-) Elapsed time since last frame */ }; /**
--- a/libcore/core/window.h Wed Oct 14 18:20:58 2020 +0200 +++ b/libcore/core/window.h Thu Oct 15 09:21:04 2020 +0200 @@ -31,9 +31,9 @@ * \brief Global exposed window structure. */ struct window { - unsigned int w; /*!< (RO) Window width. */ - unsigned int h; /*!< (RO) Window height. */ - void *handle; /*!< (RO) Native handle. */ + unsigned int w; /*!< (-) Window width. */ + unsigned int h; /*!< (-) Window height. */ + void *handle; /*!< (*) Native handle. */ }; /**