doxygen.cpp

Go to the documentation of this file.
00001 //! @file doxygen.cpp
00002 //! Text and HTML-code for the startpage of the doxygen-documentation.
00003 
00004 /*
00005     This file contains no code, and is only used when generating documentation.
00006     It serves as a place for the main page text and various developer documentation.
00007 */
00008 
00009 // ===========================================================================
00010 //  Main page
00011 // ===========================================================================
00012 
00013 /**
00014 
00015 @mainpage Developer Documentation
00016 
00017     <table border="0">
00018     <tr>
00019     <td valign="top">
00020         @image html wesnoth-icon.png
00021     </td>
00022     <td>
00023         <h3>Howto</h3>
00024         @li @ref get_involved
00025         @li @ref howto_document
00026 
00027     </td>
00028     </tr>
00029 
00030     <tr>
00031     <td valign="top">
00032         @image html konrad-commander.png
00033     </td>
00034     <td>
00035         <h3>Reference</h3>
00036         @li <a href="namespaces.html">Namespaces</a>
00037         @li @ref unnamed_namespace
00038         @li <a href="hierarchy.html">Classes</a>
00039         @li <a href="files.html">Source Files</a>
00040         @li <a href="todo.html">Todo</a>
00041     </td>
00042     </tr>
00043     </table>
00044 
00045 */
00046 
00047 // ===========================================================================
00048 //  namespace about
00049 // ===========================================================================
00050 
00051 /*-
00052 
00053 @namespace about    Display credits about all contributors.
00054 
00055 This module is used from the startup screen.
00056 When show_about() is called, a list of contributors
00057 to the game will be presented to the user.
00058 
00059 */
00060 
00061 // ===========================================================================
00062 //  namespace dialogs
00063 // ===========================================================================
00064 
00065 /**
00066 
00067 @namespace dialogs  Various uncategorised dialogs.
00068 
00069 */
00070 
00071 // ===========================================================================
00072 //  namespace events
00073 // ===========================================================================
00074 
00075 /**
00076 
00077 @namespace events   Handling of system events.
00078 
00079 System events include mouse and key events, and other events which
00080 are not domain specific.
00081 The program maintains a stack of event_context objects,
00082 the top of the stack being the active event_context.
00083 
00084 When an object of a type inheriting from handler is
00085 instantiated, it will be associated with the active event_context
00086 (unless auto_join has been set false, in which case it can manually
00087 be instructed to join a later context). As long as its event_context
00088 remains active, and only then, it will receive all system events.
00089 
00090 @note Multiple handler objects will receive the same events,
00091 including key events.
00092 
00093 */
00094 
00095 // ===========================================================================
00096 //  namespace font
00097 // ===========================================================================
00098 
00099 /**
00100 
00101 @namespace font Graphical text output.
00102 
00103 This module is used to display and measure text.
00104 Text can optionally contain special characters, which may
00105 change specified display properties such as colour
00106 or font size.
00107 If special characters are turned on,
00108 they can be escaped, C-style, using backslashes.
00109 
00110 */
00111 
00112 // ===========================================================================
00113 //  namespace game_config
00114 // ===========================================================================
00115 
00116 /**
00117 
00118 @namespace game_config  Game configuration data as global variables.
00119 
00120 This module can be used to load various high level
00121 game configuration data from a .cfg file.
00122 The loaded data will subsequently be accessible via the
00123 global variables.
00124 
00125 */
00126 
00127 // ===========================================================================
00128 //  namespace game_events
00129 // ===========================================================================
00130 
00131 /**
00132 
00133 @namespace game_events  Domain specific events
00134 
00135 This module defines the game's event mechanism. Events might be units
00136 moving or fighting, or when victory or defeat occurs. A scenario's
00137 configuration file will define actions to take when certain events
00138 occur. This module is responsible for making sure that when the events
00139 occur, the actions take place.
00140 
00141 Game events have nothing to do with mouse movement, keyboard events, etc.
00142 These kinds of system events can be handled using namespace @ref events
00143 
00144 */
00145 
00146 // ===========================================================================
00147 //  namespace gui
00148 // ===========================================================================
00149 
00150 /**
00151 
00152 @namespace gui  General purpose widgets.
00153 
00154 This module primarily contains a number of common, general purpose
00155 widgets for the construction of composite user interfaces.
00156 
00157 */
00158 
00159 // ===========================================================================
00160 //  namespace hotkey
00161 // ===========================================================================
00162 
00163 /**
00164 
00165 @namespace hotkey   Keyboard shortcuts for game actions.
00166 
00167 Hotkey commands can be loaded from configuration objects.
00168 When a keyboard event corresponding to a hotkey occurs,
00169 a command_executor object can execute the hotkeys actions.
00170 For this to work, key_event() must be called whenever a keyboard event happens.
00171 
00172 */
00173 
00174 // ===========================================================================
00175 //  namespace image
00176 // ===========================================================================
00177 
00178 /*- already documented
00179 
00180 @namespace image    Cache of images.
00181 
00182 This module manages the cache of images. With an image name, you can get
00183 the surface corresponding to that image, and don't need to free the image.
00184 Note that surfaces returned from here are invalidated whenever events::pump()
00185 is called, and so shouldn't be kept, but should be regotten from here as
00186 needed.
00187 
00188 images come in a number of varieties:
00189  - unscaled: no modifications have been done on the image.
00190  - scaled: images are scaled to the size of a tile
00191  - greyed: images are scaled and in greyscale
00192  - brightened: images are scaled and brighter than normal.
00193 
00194 */
00195 
00196 // ===========================================================================
00197 //  namespace mp
00198 // ===========================================================================
00199 
00200 /*- already documented
00201 
00202 @namespace mp   Multiplayer meeting place and game creation.
00203 
00204 This module controls the multiplayer lobby.
00205 The lobby is a section on the server which allows players
00206 to chat, create games, and join games.
00207 
00208 */
00209 
00210 // ===========================================================================
00211 //  namespace network
00212 // ===========================================================================
00213 
00214 /**
00215 
00216 @namespace network  High level network layer for config object transport.
00217 
00218 This module provides high level network access using an API similiar
00219 to sockets, but primarily for the transport of @ref config objects.
00220 This is how the games protocols work - data is sent via config objects.
00221 
00222 A client would create a @ref manager object to initialize
00223 the network layer, connect(), and then send_data().
00224 A server would create a @ref server_manager object,
00225 then accept_connection(), and finally receive_data().
00226 
00227 */
00228 
00229 // ===========================================================================
00230 //  namespace preferences
00231 // ===========================================================================
00232 
00233 /**
00234 
00235 @namespace preferences  Modify, read and display user preferences.
00236 
00237 This module contain GUI code to display dialogs regarding
00238 user preferences, and functions which read and modify the preferences.
00239 
00240 */
00241 
00242 // ===========================================================================
00243 //  namespace reports
00244 // ===========================================================================
00245 
00246 /**
00247 
00248 @namespace reports  Unit and team statistics.
00249 
00250 This module can provide statistics and information, such as these
00251 presented in the in-game windows rightmost and upper borders.
00252 This is primarily characteristics of units and teams.
00253 
00254 */
00255 
00256 // ===========================================================================
00257 //  namespace sound
00258 // ===========================================================================
00259 
00260 /**
00261 
00262 @namespace sound    Audio output for sound and music.
00263 
00264 This module provides the ability to play music and sounds.
00265 Setting music volume to 0 will stop the music.
00266 
00267 */
00268 
00269 // ===========================================================================
00270 //  namespace tooltips
00271 // ===========================================================================
00272 
00273 /**
00274 
00275 @namespace tooltips tooltips.
00276 
00277 This module can be used to register tooltips,
00278 which will be shown provided @ref process()
00279 is called every time mouse motion events
00280 are received from the @ref events system.
00281 If tooltips::draw_text() is used instead of font::draw_text(),
00282 the text will also be registered as a tooltip.
00283 
00284 */
00285 
00286 // ===========================================================================
00287 //  Tutorials
00288 // ===========================================================================
00289 
00290 /**
00291 
00292 @page get_involved  Get Involved
00293 
00294 Apart from development, there are
00295 <a href="http://www.wesnoth.org/wiki/FAQ">other ways to contribute</a>
00296 to the project.
00297 
00298 Before you can join the development team, your work
00299 needs to be reviewed by a current developer.
00300 It works like this:
00301 you first get the
00302 <a href="http://gna.org/svn/?group=wesnoth">latest source code</a>
00303 and then submit your modified source code as
00304 <a href="http://www.kegel.com/academy/opensource.html">patches</a> to
00305 <a href="http://gna.org/patch/?group=wesnoth">Gna!</a>.
00306 Eventually, you may be given
00307 <a href="http://svnbook.org">SVN access</a>.
00308 
00309 One way to contribute is to find an unassigned bug in the
00310 <a href="http://gna.org/bugs/?group=wesnoth">bug repository</a>
00311 and fix the bug.
00312 If you wish to work on something else, you should probably
00313 explain on the
00314 <a href="http://www.wesnoth.org/forum/">forum</a>
00315 what you wish to do before doing any actual development.
00316 Do make sure you have read the projects
00317 <a href="http://www.wesnoth.org/wiki/CodingStandards">coding standards</a>.
00318 When adding new features, keep in mind the project philosophy,
00319 which is that of
00320 <a href="http://www.wesnoth.org/wiki/WesnothPhilosophy">KISS</a>.
00321 
00322 Other than at the forum, developers may also hang out
00323 in IRC #wesnoth-dev at irc.freenode.net
00324 
00325 */
00326 
00327 /**
00328 
00329 @page howto_document    Document your code
00330 
00331 @section motivation Motivation
00332 
00333 The document you are reading now was generated using
00334 <a href="http://www.doxygen.org/">Doxygen</a>.
00335 It follows in the tradition of
00336 <a href="http://www.literateprogramming.com/">literal programming</a>,
00337 the goal of which is to keep documentation in the source code,
00338 when practical.
00339 This way, the documentation will not be outdated or unmaintained.
00340 
00341 @section interfaces Commenting interfaces
00342 
00343 Concise comments are prefered, as long as the explanation
00344 is correct, is not open to interpretation and does not
00345 assume extensive knowledge of other parts of the system.
00346 
00347 By interface, we mean all content of a header file which
00348 is available from a C++ source file, and could result in
00349 compile errors if removed.
00350 When you comment a header file, you need to take care
00351 of a few, minor things in order to produce readable
00352 documentation using Doxygen.
00353 The basic guidelines for this project are:
00354 
00355 - When commenting part of an interface, use two slashes followed by
00356   an exclamation sign, followed by a space and then the actual comment.
00357   The first sentence you write, terminated by a period,
00358   will be the brief description.
00359   After that, you can write a longer, more detailed description.
00360   The brief description will be shown in overviews,
00361   so it should be no more than a single line.
00362   It is possible to document virtually all parts of an interface,
00363   so it is not limited to classes.
00364 
00365 Example:
00366 @code
00367 / / ! Takes care of displaying the map and game-data on the screen.
00368 / / !
00369 / / ! The display is divided into two main sections: the game area,
00370 / / ! which displays the tiles of the game board, and units on them,
00371 / / ! and the side bar, which appears on the right hand side.
00372 / / ! The side bar display is divided into three sections.
00373 class display {
00374    ...
00375 };
00376 @endcode
00377 
00378 - Do not refer to multiple objects of the type "Manager"
00379   as "Managers" or "manager". Instead, say "Manager objects".
00380   Doxygen will automatically link to class documentation
00381   whenever it finds class names in comments,
00382   but will not do so if you do not use their proper names.
00383 
00384 - Many <a href="http://www.stack.nl/~dimitri/doxygen/commands.html">Doxygen commands</a>
00385   can be used in comments to enhance the generated documentation and structure the comments.
00386 - There is a balance between readable autogenerated documentation and readable code,
00387   so beware of overdoing it.
00388 
00389 Example:
00390 @code
00391 / / ! @param a  an integer dividend
00392 / / ! @param b  an integer divisor, which must not be zero
00393 / / ! @returns  a / b
00394 / / !
00395 / / ! @pre b != 0
00396 / / ! @post divide' = a / b
00397 / / !
00398 / / ! @throws std::runtime_error
00399 / / ! @todo this has not been peer reviewed yet
00400 int divide(int a,int b) {
00401     return a / b;
00402 }
00403 @endcode
00404 
00405 */
00406 
00407 // ===========================================================================
00408 //  Reference
00409 // ===========================================================================
00410 
00411 /**
00412     @defgroup unnamed_namespace Unnamed Namespace
00413 
00414     @{
00415 */
00416 
00417 /** -file actions.hpp */
00418 /** -file ai_attack.hpp */
00419 /** -file ai.hpp */
00420 /** -file ai_move.hpp */
00421 /** -file config.hpp */
00422 /** -file display.hpp */
00423 /** -file filesystem.hpp */
00424 /** @file game.hpp */
00425 /** -file gamestatus.hpp */
00426 /** @file intro.hpp */
00427 /** @file key.hpp */
00428 /** @file language.hpp */
00429 /** -file log.hpp */
00430 /** @file mapgen_dialog.hpp */
00431 /** -file mapgen.hpp */
00432 /** -file map.hpp */
00433 /** -file multiplayer_client.hpp */
00434 /** -file multiplayer_connect.hpp */
00435 /** @file multiplayer.hpp */
00436 /** -file pathfind.hpp */
00437 /** -file playlevel.hpp */
00438 /** @file playturn.hpp */
00439 /** @file race.hpp */
00440 /** @file replay.hpp */
00441 /** -file sdl_utils.hpp */
00442 /** @file team.hpp */
00443 /** @file terrain.hpp */
00444 /** -file theme.hpp */
00445 /** -file unit.hpp */
00446 /** @file unit_types.hpp */
00447 /** -file util.hpp */
00448 /** @file video.hpp */
00449 
00450 /** @} */
00451 
00452 //.

Generated by doxygen 1.5.5 on 23 May 2008 for The Battle for Wesnoth
Gna! | Forum | Wiki | CIA | devdocs