From ce473ed9fe7c6cf8dc5a4723509eaa9721c91fa5 Mon Sep 17 00:00:00 2001 From: Per Inge Mathisen Date: Sat, 16 Feb 2008 13:05:34 +0000 Subject: [PATCH] Add some more doxygen comments. git-svn-id: svn+ssh://svn.gna.org/svn/warzone/trunk@3796 4a71c877-e1ca-e34f-864e-861f7616d084 --- lib/framework/trig.h | 6 ++++-- src/action.c | 6 +++--- src/advvis.c | 8 +++++--- src/ai.c | 4 ++-- src/astar.c | 4 ++-- src/atmos.c | 9 ++++----- src/aud.c | 8 +++----- src/bridge.c | 24 ++++++++++++------------ src/bucket3d.c | 12 +++++------- src/cheat.c | 5 ++++- src/combat.c | 4 ++-- src/component.c | 8 +++----- src/configuration.c | 5 +++-- src/data.c | 6 +++--- src/design.c | 4 ++-- src/difficulty.c | 6 ++++-- src/display.c | 4 ++-- src/display3d.c | 6 +++--- src/drive.c | 9 ++++----- src/droid.c | 6 +++--- src/functiondef.h | 2 +- src/hci.c | 5 +++-- src/main.c | 28 ++++++++++++++++++++++++++-- src/power.c | 4 ++-- 24 files changed, 105 insertions(+), 78 deletions(-) diff --git a/lib/framework/trig.h b/lib/framework/trig.h index 175124e86..56253c623 100644 --- a/lib/framework/trig.h +++ b/lib/framework/trig.h @@ -17,8 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/** \file - * * \brief Interface to trig lookup tables +/** + * @file + * + * Interface to trig lookup tables. */ #ifndef _trig_h diff --git a/src/action.c b/src/action.c index eced2d2e7..d322fac17 100644 --- a/src/action.c +++ b/src/action.c @@ -17,10 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Action.c +/** + * @file action.c * - * Functions for setting the action of a droid + * Functions for setting the action of a droid. * */ #include diff --git a/src/advvis.c b/src/advvis.c index bf490fc52..d910ef826 100644 --- a/src/advvis.c +++ b/src/advvis.c @@ -17,9 +17,11 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* AdvVis.c Alex McLean */ -/* Experiment - possibly only for the faster configurations */ -/* Makes smooth transitions for terrain visibility */ +/** + * @file advvis.c + * + * Makes smooth transitions for terrain visibility. + */ #include "lib/framework/frame.h" #include "lib/gamelib/gtime.h" diff --git a/src/ai.c b/src/ai.c index ad91535e1..569daa660 100644 --- a/src/ai.c +++ b/src/ai.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * AI.c +/** + * @file ai.c * * AI update functions for the different object types. * diff --git a/src/astar.c b/src/astar.c index 75fbf677f..e9a19a40a 100644 --- a/src/astar.c +++ b/src/astar.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * AStar.c +/** + * @file aStar.c * * A* based findpath * diff --git a/src/atmos.c b/src/atmos.c index 080b907df..4ad3ec419 100644 --- a/src/atmos.c +++ b/src/atmos.c @@ -17,11 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* Atmos.c - Handles atmospherics such as snow and rain */ -/* Alex McLean, Pumpkin Studios, EIDOS Interactive */ -/* - At present, the water effects are part of the atmos - system and aren't properly implemented in the software mode +/** + * @file atmos.c + * + * Handles atmospherics such as snow and rain. */ #include "lib/framework/frame.h" #include "lib/ivis_common/piedef.h" diff --git a/src/aud.c b/src/aud.c index f89c15395..322edec23 100644 --- a/src/aud.c +++ b/src/aud.c @@ -17,13 +17,11 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/***************************************************************************/ -/* - * Aud.c +/** + * @file aud.c * - * Warzone audio wrapper functions + * Warzone audio wrapper functions. * - * Gareth Jones 16/12/97 */ /***************************************************************************/ diff --git a/src/bridge.c b/src/bridge.c index bfb43501f..363ee3c3f 100644 --- a/src/bridge.c +++ b/src/bridge.c @@ -30,18 +30,18 @@ #include "effects.h" #include "bridge.h" - -/* -Bridge.c -Alex McLean, Pumpkin Studios EIDOS Interactive, 1998. -Handles rendering and placement of bridging sections for -traversing water and ravines?! My guess is this won't make it into -the final game, but we'll see... - -He was right. It did not make the final game. The code below -is unused. Can it be reused? - Per, 2007 -*/ - +/** + * @file bridge.c + * Bridges - currently unused. + * + * Handles rendering and placement of bridging sections for + * traversing water and ravines?! My guess is this won't make it into + * the final game, but we'll see... + * Alex McLean, Pumpkin Studios EIDOS Interactive, 1998. + * + * He was right. It did not make the final game. The code below + * is unused. Can it be reused? - Per, 2007 + */ /* Returns TRUE or FALSE as to whether a bridge is valid. diff --git a/src/bucket3d.c b/src/bucket3d.c index 45798d1ed..dad1fbf46 100644 --- a/src/bucket3d.c +++ b/src/bucket3d.c @@ -17,13 +17,11 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - bucket3D.c - stores object render calls in a linked list renders after bucket sorting objects - - ------------------------------------------------- - Jeremy Sallis, Pumpkin Studios, EIDOS INTERACTIVE - ------------------------------------------------- -*/ +/** + * @file bucket3D.c + * + * Stores object render calls in a linked list renders after bucket sorting objects. + */ /* Includes direct access to matrix code */ #include "lib/ivis_common/piedef.h" diff --git a/src/cheat.c b/src/cheat.c index 5169952d3..6d9619ecc 100644 --- a/src/cheat.c +++ b/src/cheat.c @@ -17,7 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* Handles cheat codes for Warzone */ +/** + * @file cheat.c + * Handles cheat codes for Warzone. + */ /* Alex M 19th - Jan. 1999 */ #include "lib/framework/frame.h" diff --git a/src/combat.c b/src/combat.c index 2a74c1090..3513a9c59 100644 --- a/src/combat.c +++ b/src/combat.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Combat.c +/** + * @file combat.c * * Combat mechanics routines. * diff --git a/src/component.c b/src/component.c index b10ea84d6..539de0aab 100644 --- a/src/component.c +++ b/src/component.c @@ -17,11 +17,9 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - Component.c - Draws component objects - oh yes indeed. - Alex M, Pumpkin Studios, EIDOS Interactive, 1997. - +/** + * @file component.c + * Draws component objects - oh yes indeed. */ #include diff --git a/src/configuration.c b/src/configuration.c index 26978c1f6..40b99ebc1 100644 --- a/src/configuration.c +++ b/src/configuration.c @@ -17,8 +17,9 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - *Config.c saves your favourite options to the Registry. +/** + * @file config.c + * Saves your favourite options to the Registry. * */ #include diff --git a/src/data.c b/src/data.c index f4934acb2..82958f35b 100644 --- a/src/data.c +++ b/src/data.c @@ -17,10 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Data.c +/** + * @file data.c * - * Data loading functions used by the framework resource module + * Data loading functions used by the framework resource module. * */ #include diff --git a/src/design.c b/src/design.c index 3b9440a59..19928accf 100644 --- a/src/design.c +++ b/src/design.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Design.c +/** + * @file design.c * * Functions for design screen. * diff --git a/src/difficulty.c b/src/difficulty.c index f9f48cb1c..7c5404b85 100644 --- a/src/difficulty.c +++ b/src/difficulty.c @@ -17,9 +17,11 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -// ------------------------------------------------------------------------------------ /* Simple short file - only because there was nowhere else for it logically to go */ -/* Handes the difficulty level effects on gameplay */ +/** + * @file difficulty.c + * Handes the difficulty level effects on gameplay. + */ /* diff --git a/src/display.c b/src/display.c index 4560be401..b8d57b44c 100644 --- a/src/display.c +++ b/src/display.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Display.c +/** + * @file display.c * * Display routines. * diff --git a/src/display3d.c b/src/display3d.c index 6b47d2218..9aff25297 100644 --- a/src/display3d.c +++ b/src/display3d.c @@ -17,9 +17,9 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - Display3D.c - draws the 3D terrain view. Both the 3D and pseudo-3D components:- - textured tiles. +/** + * @file display3D.c + * Draws the 3D terrain view. Both the 3D and pseudo-3D components - textured tiles. ------------------------------------------------------------------- - Alex McLean & Jeremy Sallis, Pumpkin Studios, EIDOS INTERACTIVE - diff --git a/src/drive.c b/src/drive.c index 76e1b6478..2985ab181 100644 --- a/src/drive.c +++ b/src/drive.c @@ -17,11 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -// -// Drive.c -// -// Routines for player driving units about the map. -// +/** + * @file drive.c + * Routines for player driving units about the map. + */ #define DEFINE_DRIVE_INLINE diff --git a/src/droid.c b/src/droid.c index acfd87eef..10b98657c 100644 --- a/src/droid.c +++ b/src/droid.c @@ -17,10 +17,10 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Droid.c +/** + * @file droid.c * - * Droid method functions + * Droid method functions. * */ diff --git a/src/functiondef.h b/src/functiondef.h index 292616495..8a4972f3e 100644 --- a/src/functiondef.h +++ b/src/functiondef.h @@ -18,7 +18,7 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ /** \file - * Definitios for functions. + * Definitions for functions. */ #ifndef __INCLUDED_FUNCTIONDEF_H__ diff --git a/src/hci.c b/src/hci.c index 5bceb9e6f..9fe3553fe 100644 --- a/src/hci.c +++ b/src/hci.c @@ -17,10 +17,11 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * HCI.c (Human Computer Interface - thanks to Alex for the file name). +/** + * @file hci.c * * Functions for the in game interface. + * (Human Computer Interface - thanks to Alex for the file name). * */ diff --git a/src/main.c b/src/main.c index c7d9e667f..1d011ac09 100644 --- a/src/main.c +++ b/src/main.c @@ -17,9 +17,33 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * main.c +/** + * @file main.c * + * The main file that launches the game and starts up everything. + */ + +/** @mainpage Warzone2100 Code Documentation + * + * @section intro_sec Introduction + * + * Welcome to the Warzone2100 Resurrection Project's code library! We are still only starting + * to document this code base, but it should already be useful for quickly browsing around the + * code and getting an idea of what exists and how things work. + * + * @section install_sec Where to begin + * + * @subsection step1 Step 1: Read the wiki documentation + * + * We have a great deal of documentation on our wiki page at http://wiki.wz2100.net/ which + * may help get you started. Please also take notice of our style guide! + * + * @subsection step2 Step 2: Skim main.c + * + * You may want to begin reading code with main.c, since this is where execution begins, + * and trace code paths from here. + * + * Have fun! */ // Get platform defines before checking for them! diff --git a/src/power.c b/src/power.c index 0bf8a98eb..615c60ef3 100644 --- a/src/power.c +++ b/src/power.c @@ -17,8 +17,8 @@ along with Warzone 2100; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ -/* - * Power.c +/** + * @file power.c * * Store PlayerPower and other power related stuff! *