Mercurial > molko

annotate doxygen/mainpage.c @ 147:b386d25832c8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: use new nomenclature, closes #2497
author David Demelier <markand@malikania.fr>
date Thu, 15 Oct 2020 09:21:04 +0200
parents 6203e1ac9b18
children eb0a7ab71023
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 /*
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
2 * mainpage.c -- describe "Main Page" in Doxygen
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 * Permission to use, copy, modify, and/or distribute this software for any
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 * purpose with or without fee is hereby granted, provided that the above
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
8 * copyright notice and this permission notice appear in all copies.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
17 */
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
18
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 /**
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 * \mainpage
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 * Welcome to the Molko's reference API.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
23 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 * # About
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
26 * Molko's Adventure is a 2D solo RPG written in pure C, using SDL2 and SDL2
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 * addons.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
28 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 * As its heart, the game is split into two parts, the core (**src/core**) and
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 * the game data and scenario (**src/adventure**). It is then possible to anyone
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 * to create its own similar game using the same core. However please note that:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
32 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 * - It is not a game engine! Many aspects in the core are still tightly coupled
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
34 * with the original game design. We wanted the core to be kept simple without
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 * thousands of dynamic allocations and genericity all over the place.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
36 * - It is not meant to be used as system library. Functions were kept simple
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 * and not prefixed by any "namespace"-like word. Instead, it is meant to be
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
38 * bundled with your game as boilerplate code with the possibility for you to
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 * change all internals if you want.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 * # Usage
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
42 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 * If you plan to create your own game, simply copy the whole **src/core**
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
44 * directory to your project and add all .c files to the compilation process. No
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 * prior configuration is required, every features are detected using `#ifdef`s.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
46 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 * \note If you find a bug regarding your platform, feel free to send bug
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
48 * reports and patches.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
49 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
50 * Then, check this API or read .h files for documentation. The files ending
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
51 * with _p.h are usually reserved for the implementation and should not be used
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
52 * unless you know what you're doing.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
53 *
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
54 * # Documentation nomenclature
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
56 * Every modules are organized per files and referenced this way. For example,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 * if you need to access the error handling, you just have to use \ref error.h
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
58 * file.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
59 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
60 * ## Structures
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
61 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
62 * Almost every structure are exposed directly to the user and allocated on the
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
63 * stack. Each member is documented with the following prefix format (XYZ)
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
64 * where:
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
65 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
66 * The letter *X* defines the following restriction
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
67 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
68 * - `+`: The property is readable/editable by the user,
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
69 * - `-`: The property is readable by the user,
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
70 * - `*`: The property is not meant to be used directly by the user.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
71 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
72 * The letter *Y* can be set to `&` in that case means it is only referenced
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
73 * and is not an owned property (usually a non-owning pointer). Which means
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
74 * user is responsible for deallocation if required.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
75 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
76 * The finall letter *Z* can be set to `?` which means it is optional (like a
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
77 * nullable pointer).
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
78 *
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
79 * Examples:
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
80 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
81 * ```c
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
82 * struct foo {
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
83 * int x; // (+) Position in x.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
84 * int y; // (+) Position in y.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
85 * struct theme *th; // (+&?) Theme to use.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
86 * unsigned int elapsed; // (-) Elapsed time since last frame.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
87 * struct texture text; // (*) Texture used for rendering.
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
88 * };
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
89 * ```
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
90 *
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
91 * Within this structure, the fields `x` and `y` are completely accessible to
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
92 * the user for both reading/writing. The field `th` is an optional non-owning
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
93 * pointer to a theme which is also readable/writable. The field `elapsed` is
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
94 * readable but should not be modified. Finally, the field `text` is private
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
95 * and should not be touched by the user.
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 * ## Functions
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
98 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
99 * When functions needs to initialize and destroy objects, the following
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
100 * conventions is used:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 * - `foo_init`: initialize the object,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 * - `foo_finish`: dispose the object and possible owned allocations.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 * In case of opaque objects, the creation function is named under the module
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 * discretion (e.g. `foo_open`, `foo_new`) but the destruction function is
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 * usually named `foo_free`.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 * # Usage conventions
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 * This chapter describes lots of aspects about using this core API.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
113 * ## Memory and ownership
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 * Within the core, functions usually never take ownership of user objects. They
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 * mostly assume that objects are still alive during usage of the core API. If
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 * the opposite case happen, it is clearly stated in the documentation. Unless
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 * stated, user must always make sure objects are kept alive.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
119 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
120 * If a function needs its own copy of something, it usually take a const
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
121 * pointer and copy it into its internals. But make sure that every member are
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 * still pointer to valid memory if this is a concern.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 * Example: the \ref script.h modules is used to create a sequence of action, on
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 * its internal it stores a singly-linked list of \ref action that are copied
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 * from the user. But since the \ref action structure contains arbitrary data,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 * those must be kept until the action is no longer used.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 * struct action my_action action = {
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 * .data = my_action_data,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 * .update = my_action_update
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 * };
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
134 * struct script script;
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
136 * script_init(&script);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 * script_append(&script, &action);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
138 * \endcode
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
139 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
140 * Even though \ref script_append copy the action into an internal object,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 * the *my_action_data* must still be valid until the script ended.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
143 * ## Modules
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
144 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 * Whenever possible, functions that needs a structure context will always take
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
146 * it as first argument.
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
147 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
148 * This let the user to control lifetime and allocation storage for most of the
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
149 * API objects.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 * Example:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
152 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
153 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
154 * struct clock clock;
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
155 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
156 * clock_start(&clock);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
157 * clock_elapsed(&clock);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 * \endcode
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
159 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
160 * ## Thread safety and reentrancy
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
162 * The core API is **not** thread-safe at all. Any module must always be used in
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 * a single thread unless you really know what you're doing.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 *
147
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
165 * Most of the API is reentrant though except the some modules which use global
b386d25832c8 doc: use new nomenclature, closes #2497
David Demelier <markand@malikania.fr>
parents: 72
diff changeset
166 * objects.
72
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
167 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
168 * \note This may change in the future.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
169 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
170 * ## Error handling
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
171 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
172 * Functions that may fail usually return a boolean. If an error occured, it is
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
173 * stored in a global variable that are accessed through the \ref error.h
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
174 * module.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
175 */