Mercurial > molko
annotate doxygen/mainpage.c @ 167:b9b826cd9832
core: texture_(scale|draw) now return a bool
author | David Demelier <markand@malikania.fr> |
---|---|
date | Tue, 20 Oct 2020 14:58:51 +0200 |
parents | b386d25832c8 |
children | eb0a7ab71023 |
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 */ |