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

@@ -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

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 <string.h>

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"

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.
  *

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
  *

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"

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
  */
 /***************************************************************************/
 

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.

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"

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"

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.
  *

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 <string.h>
 

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 <string.h>

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 <string.h>

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.
  *

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.
+ */
 
 
 /*

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.
  *

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 -

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
 

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.
  *
  */
 

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__

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).
  *
  */
 

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!

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!
  *