Mercurial > molko

annotate doxygen/mainpage.c @ 100:ef9135c34505

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
message: improve rendering and add example
author David Demelier <markand@malikania.fr>
date Tue, 31 Mar 2020 10:57:14 +0200
parents 6203e1ac9b18
children b386d25832c8
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 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 * # Documentation convention
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
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
63 * stack. Each member is documented with the following prefix:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
64 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
65 * - `(RW)`: The property is readable/editable by the user,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
66 * - `(RO)`: The property is readable by the user,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
67 * - `(PV)`: The property is not meant to be used directly by the user.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
68 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
69 * ## Functions
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
70 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
71 * 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
72 * conventions is used:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
73 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
74 * - `foo_init`: initialize the object,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
75 * - `foo_finish`: dispose the object and possible owned allocations.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
76 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
77 * 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
78 * 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
79 * usually named `foo_free`.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
80 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
81 * # Usage conventions
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
82 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 * 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
84 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 * ## Memory and ownership
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 * 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
88 * 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
89 * 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
90 * 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
91 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
92 * 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
93 * 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
94 * 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
95 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 * 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
97 * 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
98 * 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
99 * 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
100 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
102 * struct action my_action action = {
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 * .data = my_action_data,
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 * .update = my_action_update
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 * };
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 * struct script script;
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
107 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
108 * script_init(&script);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
109 * script_append(&script, &action);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 * \endcode
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 * 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
113 * 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
114 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 * ## Modules
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 * Whenever possible, functions that needs a structure context will always take
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
118 * it as first argument. Opaque structures may be returned by pointers instead.
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 * 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
121 * API objects.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
122 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 * Example:
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
125 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 * struct clock clock;
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 * clock_start(&clock);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
129 * clock_elapsed(&clock);
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 * \endcode
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 * Example (opaque object):
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 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
135 * struct texture *tex;
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
136 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
137 * tex = image_openf("foo.png");
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 * ## Thread safety and reentrancy
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
141 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
142 * 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
143 * 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
144 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
145 * Most of the API is reentrant though except the \ref window.h and \ref error.h
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
146 * which use global objects.
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 * \note This may change in the future.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
149 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
150 * ## Error handling
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
151 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
152 * 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
153 * 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
154 * module.
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 * However, functions returning an opaque object may return NULL instead.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
157 *
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
158 * Example:
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 * \code
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
161 * if (!sys_init())
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
162 * error_fatalf(); // Print an error and exits.
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
163 * \endcode
6203e1ac9b18 doc: improve doxygen documentation a lot
David Demelier <markand@malikania.fr>
parents:
diff changeset
164 */