The Battle for Wesnoth  1.13.10+dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
doxygen.cpp
Go to the documentation of this file.
1 //! @file doxygen.cpp
2 //! Text and HTML-code for the startpage of the doxygen-documentation.
3 
4 /*
5  This file contains no code, and is only used when generating documentation.
6  It serves as a place for the main page text and various developer documentation.
7 */
8 
9 // ===========================================================================
10 // Main page
11 // ===========================================================================
12 
13 /**
14 
15 @mainpage Developer Documentation
16 
17  <table border="0">
18  <tr>
19  <td valign="top">
20  @image html wesnoth-icon.png
21  </td>
22  <td>
23  <h3>Howto</h3>
24  @li @ref get_involved
25  @li @ref howto_document
26 
27  </td>
28  </tr>
29 
30  <tr>
31  <td valign="top">
32  @image html portraits/humans/mage.png
33  </td>
34  <td>
35  <h3>Reference</h3>
36  @li <a href="namespaces.html">Namespaces</a>
37  @li @ref unnamed_namespace
38  @li <a href="hierarchy.html">Classes</a>
39  @li <a href="files.html">Source Files</a>
40  @li <a href="todo.html">Todo</a>
41  @li <a href="deprecated.html">Deprecated</a>
42  </td>
43  </tr>
44  </table>
45 
46 */
47 
48 // ===========================================================================
49 // namespace about
50 // ===========================================================================
51 
52 /*-
53 
54 @namespace about Display credits about all contributors.
55 
56 This module is used from the startup screen.
57 When show_about() is called, a list of contributors
58 to the game will be presented to the user.
59 
60 */
61 
62 // ===========================================================================
63 // namespace dialogs
64 // ===========================================================================
65 
66 /**
67 
68 @namespace dialogs Various uncategorised dialogs.
69 
70 */
71 
72 // ===========================================================================
73 // namespace events
74 // ===========================================================================
75 
76 /**
77 
78 @namespace events Handling of system events.
79 
80 System events include mouse and key events, and other events which
81 are not domain specific.
82 The program maintains a stack of event_context objects,
83 the top of the stack being the active event_context.
84 
85 When an object of a type inheriting from handler is
86 instantiated, it will be associated with the active event_context
87 (unless auto_join has been set false, in which case it can manually
88 be instructed to join a later context). As long as its event_context
89 remains active, and only then, it will receive all system events.
90 
91 @note Multiple handler objects will receive the same events,
92 including key events.
93 
94 */
95 
96 // ===========================================================================
97 // namespace font
98 // ===========================================================================
99 
100 /**
101 
102 @namespace font Graphical text output.
103 
104 This module is used to display and measure text.
105 Text can optionally contain special characters, which may
106 change specified display properties such as colour
107 or font size.
108 If special characters are turned on,
109 they can be escaped, C-style, using backslashes.
110 
111 */
112 
113 // ===========================================================================
114 // namespace game_config
115 // ===========================================================================
116 
117 /**
118 
119 @namespace game_config Game configuration data as global variables.
120 
121 This module can be used to load various high level
122 game configuration data from a .cfg file.
123 The loaded data will subsequently be accessible via the
124 global variables.
125 
126 */
127 
128 // ===========================================================================
129 // namespace game_events
130 // ===========================================================================
131 
132 /**
133 
134 @namespace game_events Domain specific events
135 
136 This module defines the game's event mechanism. Events might be units
137 moving or fighting, or when victory or defeat occurs. A scenario's
138 configuration file will define actions to take when certain events
139 occur. This module is responsible for making sure that when the events
140 occur, the actions take place.
141 
142 Game events have nothing to do with mouse movement, keyboard events, etc.
143 These kinds of system events can be handled using namespace @ref events
144 
145 */
146 
147 // ===========================================================================
148 // namespace gui
149 // ===========================================================================
150 
151 /**
152 
153 @namespace gui General purpose widgets.
154 
155 This module primarily contains a number of common, general purpose
156 widgets for the construction of composite user interfaces.
157 
158 */
159 
160 // ===========================================================================
161 // namespace hotkey
162 // ===========================================================================
163 
164 /**
165 
166 @namespace hotkey Keyboard shortcuts for game actions.
167 
168 Hotkey commands can be loaded from configuration objects.
169 When a keyboard event corresponding to a hotkey occurs,
170 a command_executor object can execute the hotkeys actions.
171 For this to work, key_event() must be called whenever a keyboard event happens.
172 
173 */
174 
175 // ===========================================================================
176 // namespace image
177 // ===========================================================================
178 
179 /*- already documented
180 
181 @namespace image Cache of images.
182 
183 This module manages the cache of images. With an image name, you can get
184 the surface corresponding to that image, and don't need to free the image.
185 Note that surfaces returned from here are invalidated whenever events::pump()
186 is called, and so shouldn't be kept, but should be regotten from here as
187 needed.
188 
189 images come in a number of varieties:
190  - unscaled: no modifications have been done on the image.
191  - scaled: images are scaled to the size of a tile
192  - greyed: images are scaled and in greyscale
193  - brightened: images are scaled and brighter than normal.
194 
195 */
196 
197 // ===========================================================================
198 // namespace mp
199 // ===========================================================================
200 
201 /*- already documented
202 
203 @namespace mp Multiplayer meeting place and game creation.
204 
205 This module controls the multiplayer lobby.
206 The lobby is a section on the server which allows players
207 to chat, create games, and join games.
208 
209 */
210 
211 // ===========================================================================
212 // namespace network
213 // ===========================================================================
214 
215 /**
216 
217 @namespace network High level network layer for config object transport.
218 
219 This module provides high level network access using an API similar
220 to sockets, but primarily for the transport of @ref config objects.
221 This is how the games protocols work - data is sent via config objects.
222 
223 A client would create a @ref manager object to initialize
224 the network layer, connect(), and then send_data().
225 A server would create a @ref server_manager object,
226 then accept_connection(), and finally receive_data().
227 
228 */
229 
230 // ===========================================================================
231 // namespace preferences
232 // ===========================================================================
233 
234 /**
235 
236 @namespace preferences Modify, read and display user preferences.
237 
238 This module contain GUI code to display dialogs regarding
239 user preferences, and functions which read and modify the preferences.
240 
241 */
242 
243 // ===========================================================================
244 // namespace reports
245 // ===========================================================================
246 
247 /**
248 
249 @namespace reports Unit and team statistics.
250 
251 This module can provide statistics and information, such as these
252 presented in the in-game windows rightmost and upper borders.
253 This is primarily characteristics of units and teams.
254 
255 */
256 
257 // ===========================================================================
258 // namespace sound
259 // ===========================================================================
260 
261 /**
262 
263 @namespace sound Audio output for sound and music.
264 
265 This module provides the ability to play music and sounds.
266 Setting music volume to 0 will stop the music.
267 
268 */
269 
270 // ===========================================================================
271 // namespace tooltips
272 // ===========================================================================
273 
274 /**
275 
276 @namespace tooltips tooltips.
277 
278 This module can be used to register tooltips,
279 which will be shown provided @ref process()
280 is called every time mouse motion events
281 are received from the @ref events system.
282 If tooltips::draw_text() is used instead of font::draw_text(),
283 the text will also be registered as a tooltip.
284 
285 */
286 
287 // ===========================================================================
288 // Tutorials
289 // ===========================================================================
290 
291 /**
292 
293 @page get_involved Get Involved
294 
295 Before you can join the development team, your work
296 needs to be reviewed by other developers.
297 
298 - Clone the <a href="https://wiki.wesnoth.org/WesnothRepository">Git repository</a> to obtain access to the latest source code.
299 - Read up on our C++ <a href="https://wiki.wesnoth.org/CodingStandards">coding standards</a>.
300 - Check the <a href="https://wiki.wesnoth.org/PatchSubmissionGuidelines">Patch Submission Guidelines</a> and the <a href="https://wiki.wesnoth.org/DeveloperGuide">Developer Guide</a> for information on best practices for authoring Git commits.
301 - Submit your pull requests on <a href="https://github.com/wesnoth/wesnoth/">GitHub</a>.
302 
303 One way to contribute is to find an unassigned bug in the
304 <a href="http://gna.org/bugs/?group=wesnoth">bug tracker</a>
305 and fix it.
306 If you wish to work on something else, you should probably
307 explain on the
308 <a href="https://forums.wesnoth.org/">forum</a>
309 what you wish to do before doing any actual development.
310 When adding new features, keep in mind the project philosophy,
311 which is that of
312 <a href="https://wiki.wesnoth.org/WesnothPhilosophy">KISS</a>.
313 
314 The development team hangs out in the IRC channel
315 <a href="https://webchat.freenode.net/?channels=wesnoth-dev">@#wesnoth-dev on irc.freenode.net</a>.
316 Feel free to join us and ask any questions you may have about our codebase!
317 
318 */
319 
320 /**
321 
322 @page howto_document Document your code
323 
324 @section motivation Motivation
325 
326 The document you are reading now was generated using
327 <a href="http://www.doxygen.org/">Doxygen</a>.
328 It follows in the tradition of
329 <a href="http://www.literateprogramming.com/">literal programming</a>,
330 the goal of which is to keep documentation in the source code,
331 when practical.
332 This way, the documentation will not be outdated or unmaintained.
333 
334 @section interfaces Commenting interfaces
335 
336 Concise comments are prefered, as long as the explanation
337 is correct, is not open to interpretation and does not
338 assume extensive knowledge of other parts of the system.
339 
340 By interface, we mean all content of a header file which
341 is available from a C++ source file, and could result in
342 compile errors if removed.
343 When you comment a header file, you need to take care
344 of a few, minor things in order to produce readable
345 documentation using Doxygen.
346 The basic guidelines for this project are:
347 
348 - When commenting part of an interface, use one slash followed by
349  two asterisks, followed by a line break and then the actual comment
350  with an asterisk and a space aligned to the first asterisk in the
351  opening line.
352  The first sentence you write, terminated by a period,
353  will be the brief description.
354  After that, you can write a longer, more detailed description.
355  The brief description will be shown in overviews,
356  so it should be no more than a single line.
357  It is possible to document virtually all parts of an interface,
358  so it is not limited to classes.
359 
360 Example:
361 @code
362 /** Takes care of displaying the map and game-data on the screen.
363  *
364  * The display is divided into two main sections: the game area,
365  * which displays the tiles of the game board, and units on them,
366  * and the side bar, which appears on the right hand side.
367  * The side bar display is divided into three sections.
368  */
369 class display
370 {
371  ...
372 };
373 @endcode
374 
375 - It is also possible to document symbols on the same line by using a slash
376  followed by two asterisks and a left angular bracket:
377 
378 @code
379 enum ADDON_TYPE {
380  ADDON_SP_CAMPAIGN, /**< Single-player campaign. */
381  ADDON_SP_SCENARIO, /**< Single-player scenario. */
382  ADDON_MP_CAMPAIGN, /**< Multiplayer campaign. */
383  ADDON_MP_SCENARIO, /**< Multiplayer scenario. */
384 };
385 @endcode
386 
387 - Do not refer to multiple objects of the type "Manager"
388  as "Managers" or "manager". Instead, say "Manager objects".
389  Doxygen will automatically link to class documentation
390  whenever it finds class names in comments,
391  but will not do so if you do not use their proper names.
392 
393 - Many <a href="http://www.stack.nl/~dimitri/doxygen/commands.html">Doxygen commands</a>
394  can be used in comments to enhance the generated documentation and structure the comments.
395 
396 - There is a balance between readable autogenerated documentation and readable code,
397  so beware of overdoing it.
398 
399 Example:
400 @code
401 /** @param a an integer dividend
402  * @param b an integer divisor, which must not be zero
403  * @returns a / b
404  *
405  * @pre b != 0
406  * @post divide' = a / b
407  *
408  * @throws std::runtime_error
409  * @todo this has not been peer reviewed yet
410  */
411 int divide(int a, int b)
412 {
413  return a / b;
414 }
415 @endcode
416 
417 */
418 
419 // ===========================================================================
420 // Reference
421 // ===========================================================================
422 
423 /**
424  @defgroup unnamed_namespace Unnamed Namespace
425 
426  @{
427 */
428 
429 /** -file actions.hpp */
430 /** -file ai_attack.hpp */
431 /** -file ai.hpp */
432 /** -file ai_move.hpp */
433 /** -file config.hpp */
434 /** -file display.hpp */
435 /** -file filesystem.hpp */
436 /** @file game.hpp */
437 /** -file gamestatus.hpp */
438 /** @file intro.hpp */
439 /** @file key.hpp */
440 /** @file language.hpp */
441 /** -file log.hpp */
442 /** @file mapgen_dialog.hpp */
443 /** -file mapgen.hpp */
444 /** -file map.hpp */
445 /** -file multiplayer_client.hpp */
446 /** -file multiplayer_connect.hpp */
447 /** @file multiplayer.hpp */
448 /** -file pathfind.hpp */
449 /** -file playlevel.hpp */
450 /** @file playturn.hpp */
451 /** @file race.hpp */
452 /** @file replay.hpp */
453 /** -file sdl_utils.hpp */
454 /** @file team.hpp */
455 /** @file terrain.hpp */
456 /** -file theme.hpp */
457 /** -file unit.hpp */
458 /** @file unit_types.hpp */
459 /** -file util.hpp */
460 /** @file video.hpp */
461 
462 /** @} */
463 
464 //.