(svn r8950) -Cleanup: doxygen changes. Mostly @files missing tags and a few comments style.

23 files changed, 338 insertions, 272 deletions

diff --git a/src/debug.h b/src/debug.h
index 47d7855f9..bd3c222c6 100644
--- a/src/debug.h
+++ b/src/debug.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file debug.h */
+
 #ifndef DEBUG_H
 #define DEBUG_H
 
@@ -91,7 +93,7 @@ const char *GetDebugString(void);
 	#define OTTD_PRINTF64 "ll"
 #endif
 
-// Used for profiling
+/* Used for profiling */
 #define TIC() {\
 	extern uint64 _rdtsc(void);\
 	uint64 _xxx_ = _rdtsc();\
diff --git a/src/depot_gui.cpp b/src/depot_gui.cpp
index a033fe6cd..fb0683995 100644
--- a/src/depot_gui.cpp
+++ b/src/depot_gui.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** depot_gui.cpp */
+/** @file depot_gui.cpp */
 
 #include "stdafx.h"
 #include "openttd.h"
diff --git a/src/fileio.cpp b/src/fileio.cpp
index e7e95453f..f62eb5eb7 100644
--- a/src/fileio.cpp
+++ b/src/fileio.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file fileio.cpp Standard In/Out file operations*/
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "fileio.h"
@@ -31,7 +33,7 @@ typedef struct {
 
 static Fio _fio;
 
-// Get current position in file
+/* Get current position in file */
 uint32 FioGetPos(void)
 {
 	return _fio.pos + (_fio.buffer - _fio.buffer_start) - FIO_BUFFER_SIZE;
@@ -57,7 +59,7 @@ static void FioRestoreFile(int slot)
 }
 #endif /* LIMITED_FDS */
 
-// Seek to a file and a position
+/* Seek to a file and a position */
 void FioSeekToFile(uint32 pos)
 {
 	FILE *f;
@@ -177,7 +179,7 @@ FILE *FioFOpenFile(const char *filename)
 		f = fopen(buf, "rb");
 
 #if defined SECOND_DATA_DIR
-		// tries in the 2nd data directory
+		/* tries in the 2nd data directory */
 		if (f == NULL) {
 			snprintf(buf, lengthof(buf), "%s%s", _paths.second_data_dir, filename);
 			strtolower(buf + strlen(_paths.second_data_dir) - 1);
diff --git a/src/fileio.h b/src/fileio.h
index 6ee58b32c..11e7b4ef6 100644
--- a/src/fileio.h
+++ b/src/fileio.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file fileio.h Declarations for Standard In/Out file operations*/
+
 #ifndef FILEIO_H
 #define FILEIO_H
 
diff --git a/src/fios.cpp b/src/fios.cpp
index fac9e3219..b2956f9ad 100644
--- a/src/fios.cpp
+++ b/src/fios.cpp
@@ -404,7 +404,7 @@ static byte FiosGetHeightmapListCallback(int mode, const char *file, const char
 	return FIOS_TYPE_INVALID;
 }
 
-// Get a list of Heightmaps
+/* Get a list of Heightmaps */
 FiosItem *FiosGetHeightmapList(int mode)
 {
 	static char *_fios_hmap_path = NULL;
diff --git a/src/fios.h b/src/fios.h
index 591297076..c0db84d63 100644
--- a/src/fios.h
+++ b/src/fios.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file fios.h Declarations for savegames operations */
+
 #ifndef FIOS_H
 #define FIOS_H
 
@@ -26,27 +28,27 @@ enum {
 };
 
 /* Variables to display file lists */
-extern FiosItem *_fios_list; // defined in misc_gui.c
-extern int _fios_num;        // defined in fios.c, read_only version of _fios_count
-extern int _saveload_mode;   // defined in misc_gui.c
+extern FiosItem *_fios_list; ///< defined in misc_gui.cpp
+extern int _fios_num;        ///< defined in fios.cpp, read_only version of _fios_count
+extern int _saveload_mode;   ///< defined in misc_gui.cpp
 
-// Get a list of savegames
+/* Get a list of savegames */
 FiosItem *FiosGetSavegameList(int mode);
-// Get a list of scenarios
+/* Get a list of scenarios */
 FiosItem *FiosGetScenarioList(int mode);
-// Get a list of Heightmaps
+/* Get a list of Heightmaps */
 FiosItem *FiosGetHeightmapList(int mode);
-// Free the list of savegames
+/* Free the list of savegames */
 void FiosFreeSavegameList(void);
-// Browse to. Returns a filename w/path if we reached a file.
+/* Browse to. Returns a filename w/path if we reached a file. */
 char *FiosBrowseTo(const FiosItem *item);
-// Return path, free space and stringID
+/* Return path, free space and stringID */
 StringID FiosGetDescText(const char **path, uint32 *total_free);
-// Delete a name
+/* Delete a name */
 bool FiosDelete(const char *name);
-// Make a filename from a name
+/* Make a filename from a name */
 void FiosMakeSavegameName(char *buf, const char *name, size_t size);
-// Allocate a new FiosItem
+/* Allocate a new FiosItem */
 FiosItem *FiosAlloc(void);
 
 int CDECL compare_FiosItems(const void *a, const void *b);
@@ -57,10 +59,10 @@ int CDECL compare_FiosItems(const void *a, const void *b);
 typedef struct DIR DIR;
 
 typedef struct dirent { // XXX - only d_name implemented
-	wchar_t *d_name; /* name of found file */
+	wchar_t *d_name; // name of found file
 	/* little hack which will point to parent DIR struct which will
 	 * save us a call to GetFileAttributes if we want information
-	 * about the file (for example in function fio_bla */
+	 * about the file (for example in function fio_bla) */
 	DIR *dir;
 } dirent;
 
diff --git a/src/fontcache.cpp b/src/fontcache.cpp
index 5c5a7cbee..06e6018eb 100644
--- a/src/fontcache.cpp
+++ b/src/fontcache.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file fontcache.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
diff --git a/src/functions.h b/src/functions.h
index f355a7764..4e1f3c216 100644
--- a/src/functions.h
+++ b/src/functions.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file functions.h */
+
 #ifndef FUNCTIONS_H
 #define FUNCTIONS_H
 
@@ -34,17 +36,17 @@ static inline Point RemapCoords2(int x, int y)
 }
 
 
-/* clear_land.c */
+/* clear_land.cpp */
 void DrawHillyLandTile(const TileInfo *ti);
 void DrawClearLandTile(const TileInfo *ti, byte set);
 void DrawClearLandFence(const TileInfo *ti);
 void TileLoopClearHelper(TileIndex tile);
 
-/* water_land.c */
+/* water_land.cpp */
 void DrawShipDepotSprite(int x, int y, int image);
 void TileLoop_Water(TileIndex tile);
 
-/* players.c */
+/* players.cpp */
 bool CheckPlayerHasMoney(int32 cost);
 void SubtractMoneyFromPlayer(int32 cost);
 void SubtractMoneyFromPlayerFract(PlayerID player, int32 cost);
@@ -57,7 +59,7 @@ void ShowInfo(const char *str);
 void CDECL ShowInfoF(const char *str, ...);
 void NORETURN CDECL error(const char *str, ...);
 
-/* openttd.c */
+/* openttd.cpp */
 
 /**************
  * Warning: DO NOT enable this unless you understand what it does
@@ -101,13 +103,13 @@ static inline TileIndex RandomTileSeed(uint32 r) { return TILE_MASK(r); }
 static inline TileIndex RandomTile(void) { return TILE_MASK(Random()); }
 
 
-uint32 InteractiveRandom(void); /* Used for random sequences that are not the same on the other end of the multiplayer link */
+uint32 InteractiveRandom(void); // Used for random sequences that are not the same on the other end of the multiplayer link
 uint InteractiveRandomRange(uint max);
 
-/* facedraw.c */
+/* facedraw.cpp */
 void DrawPlayerFace(uint32 face, int color, int x, int y);
 
-/* texteff.c */
+/* texteff.cpp */
 void MoveAllTextEffects(void);
 void AddTextEffect(StringID msg, int x, int y, uint16 duration);
 void InitTextEffects(void);
@@ -123,23 +125,23 @@ void DeleteAnimatedTile(TileIndex tile);
 void AnimateAnimatedTiles(void);
 void InitializeAnimatedTiles(void);
 
-/* tunnelbridge_cmd.c */
+/* tunnelbridge_cmd.cpp */
 bool CheckBridge_Stuff(byte bridge_type, uint bridge_len);
 uint32 GetBridgeLength(TileIndex begin, TileIndex end);
 int CalcBridgeLenCostFactor(int x);
 
-/* misc_cmd.c */
+/* misc_cmd.cpp */
 void PlaceTreesRandomly(void);
 
 void InitializeLandscapeVariables(bool only_constants);
 
-/* misc.c */
+/* misc.cpp */
 bool IsCustomName(StringID id);
 void DeleteName(StringID id);
 char *GetName(char *buff, StringID id, const char* last);
 
-// AllocateNameUnique also tests if the name used is not used anywere else
-//  and if it is used, it returns an error.
+/* AllocateNameUnique also tests if the name used is not used anywere else
+ * and if it is used, it returns an error. */
 #define AllocateNameUnique(name, skip) RealAllocateName(name, skip, true)
 #define AllocateName(name, skip) RealAllocateName(name, skip, false)
 StringID RealAllocateName(const char *name, byte skip, bool check_double);
@@ -203,7 +205,7 @@ enum {
 };
 void ShowSaveLoadDialog(int mode);
 
-// callback from drivers that is called if the game size changes dynamically
+/* callback from drivers that is called if the game size changes dynamically */
 void GameSizeChanged(void);
 bool FileExists(const char *filename);
 bool ReadLanguagePack(int index);
diff --git a/src/genworld.cpp b/src/genworld.cpp
index dd7d42bd3..b08b64834 100644
--- a/src/genworld.cpp
+++ b/src/genworld.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file genworld.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -87,10 +89,10 @@ static void *_GenerateWorld(void *arg)
 	SetObjectToPlace(SPR_CURSOR_ZZZ, PAL_NONE, 0, WC_MAIN_WINDOW, 0);
 
 	IncreaseGeneratingWorldProgress(GWP_MAP_INIT);
-	// Must start economy early because of the costs.
+	/* Must start economy early because of the costs. */
 	StartupEconomy();
 
-	// Don't generate landscape items when in the scenario editor.
+	/* Don't generate landscape items when in the scenario editor. */
 	if (_gw.mode == GW_EMPTY) {
 		SetGeneratingWorldProgress(GWP_UNMOVABLE, 1);
 
@@ -103,7 +105,7 @@ static void *_GenerateWorld(void *arg)
 		GenerateLandscape(_gw.mode);
 		GenerateClearTile();
 
-		// only generate towns, tree and industries in newgame mode.
+		/* only generate towns, tree and industries in newgame mode. */
 		if (_game_mode != GM_EDITOR) {
 			GenerateTowns();
 			GenerateIndustries();
@@ -112,7 +114,7 @@ static void *_GenerateWorld(void *arg)
 		}
 	}
 
-	// These are probably pointless when inside the scenario editor.
+	/* These are probably pointless when inside the scenario editor. */
 	SetGeneratingWorldProgress(GWP_GAME_INIT, 3);
 	StartupPlayers();
 	IncreaseGeneratingWorldProgress(GWP_GAME_INIT);
@@ -121,7 +123,7 @@ static void *_GenerateWorld(void *arg)
 	StartupDisasters();
 	_generating_world = false;
 
-	// No need to run the tile loop in the scenario editor.
+	/* No need to run the tile loop in the scenario editor. */
 	if (_gw.mode != GW_EMPTY) {
 		uint i;
 
@@ -230,7 +232,7 @@ void HandleGeneratingWorldAbortion(void)
 
 /**
  * Generate a world.
- * @param mode The mode of world generation (@see GenerateWorldModes).
+ * @param mode The mode of world generation (see GenerateWorldModes).
  * @param size_x The X-size of the map.
  * @param size_y The Y-size of the map.
  */
diff --git a/src/genworld.h b/src/genworld.h
index 922b51505..9c1797232 100644
--- a/src/genworld.h
+++ b/src/genworld.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file genworld.h */
+
 #ifndef GENWORLD_H
 #define GENWORLD_H
 
@@ -18,28 +20,28 @@
  * Otherwise you will get inconsistent behaviour.
  */
 enum {
-	LG_ORIGINAL     = 0,  //! The original landscape generator
-	LG_TERRAGENESIS = 1,  //! TerraGenesis Perlin landscape generator
+	LG_ORIGINAL     = 0,  ///< The original landscape generator
+	LG_TERRAGENESIS = 1,  ///< TerraGenesis Perlin landscape generator
 
-	GENERATE_NEW_SEED = (uint)-1, //! Create a new random seed
+	GENERATE_NEW_SEED = (uint)-1, ///< Create a new random seed
 };
 
 typedef void gw_done_proc(void);
 typedef void gw_abort_proc(void);
 
 typedef struct gw_info {
-	bool active;           //! Is generating world active
-	bool abort;            //! Whether to abort the thread ASAP
-	bool wait_for_draw;    //! Are we waiting on a draw event
-	bool quit_thread;      //! Do we want to quit the active thread
-	bool threaded;         //! Whether we run _GenerateWorld threaded
-	int mode;              //! What mode are we making a world in
-	PlayerID lp;               //! The local_player before generating
-	uint size_x;           //! X-size of the map
-	uint size_y;           //! Y-size of the map
-	gw_done_proc *proc;    //! Proc that is called when done (can be NULL)
-	gw_abort_proc *abortp; //! Proc that is called when aborting (can be NULL)
-	OTTDThread *thread;    //! The thread we are in (can be NULL)
+	bool active;           ///< Is generating world active
+	bool abort;            ///< Whether to abort the thread ASAP
+	bool wait_for_draw;    ///< Are we waiting on a draw event
+	bool quit_thread;      ///< Do we want to quit the active thread
+	bool threaded;         ///< Whether we run _GenerateWorld threaded
+	int mode;              ///< What mode are we making a world in
+	PlayerID lp;           ///< The local_player before generating
+	uint size_x;           ///< X-size of the map
+	uint size_y;           ///< Y-size of the map
+	gw_done_proc *proc;    ///< Proc that is called when done (can be NULL)
+	gw_abort_proc *abortp; ///< Proc that is called when aborting (can be NULL)
+	OTTDThread *thread;    ///< The thread we are in (can be NULL)
 } gw_info;
 
 #ifdef TEMPORARY_OTTDTHREAD_DEFINITION
@@ -48,16 +50,16 @@ typedef struct gw_info {
 #endif
 
 typedef enum gwp_classes {
-	GWP_MAP_INIT,    /* Initialize/allocate the map, start economy */
-	GWP_LANDSCAPE,   /* Create the landscape */
-	GWP_ROUGH_ROCKY, /* Make rough and rocky areas */
-	GWP_TOWN,        /* Generate towns */
-	GWP_INDUSTRY,    /* Generate industries */
-	GWP_UNMOVABLE,   /* Generate unmovables (radio tower, light houses) */
-	GWP_TREE,        /* Generate trees */
-	GWP_GAME_INIT,   /* Initialize the game */
-	GWP_RUNTILELOOP, /* Runs the tile loop 1280 times to make snow etc */
-	GWP_GAME_START,  /* Really prepare to start the game */
+	GWP_MAP_INIT,    ///< Initialize/allocate the map, start economy
+	GWP_LANDSCAPE,   ///< Create the landscape
+	GWP_ROUGH_ROCKY, ///< Make rough and rocky areas
+	GWP_TOWN,        ///< Generate towns
+	GWP_INDUSTRY,    ///< Generate industries
+	GWP_UNMOVABLE,   ///< Generate unmovables (radio tower, light houses)
+	GWP_TREE,        ///< Generate trees
+	GWP_GAME_INIT,   ///< Initialize the game
+	GWP_RUNTILELOOP, ///< Runs the tile loop 1280 times to make snow etc
+	GWP_GAME_START,  ///< Really prepare to start the game
 	GWP_CLASS_COUNT
 } gwp_class;
 
@@ -71,7 +73,7 @@ static inline bool IsGeneratingWorld(void)
 	return _gw.active;
 }
 
-/* genworld.c */
+/* genworld.cpp */
 void SetGeneratingWorldPaintStatus(bool status);
 bool IsGeneratingWorldReadyForPaint(void);
 bool IsGenerateWorldThreaded(void);
@@ -83,7 +85,7 @@ void AbortGeneratingWorld(void);
 bool IsGeneratingWorldAborted(void);
 void HandleGeneratingWorldAbortion(void);
 
-/* genworld_gui.c */
+/* genworld_gui.cpp */
 void SetGeneratingWorldProgress(gwp_class cls, uint total);
 void IncreaseGeneratingWorldProgress(gwp_class cls);
 void PrepareGenerateWorldProgress(void);
diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp
index b89113ad8..44b22c21a 100644
--- a/src/genworld_gui.cpp
+++ b/src/genworld_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file genworld_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "heightmap.h"
@@ -398,7 +400,7 @@ static void GenerateLandscapeWndProc(Window *w, WindowEvent *e)
 			ShowDropDownMenu(w, tree_placer, _patches_newgame.tree_placer, GLAND_TREE_PULLDOWN, 0, 0);
 			break;
 		case GLAND_LANDSCAPE_TEXT: case GLAND_LANDSCAPE_PULLDOWN: // Landscape generator OR Heightmap rotation
-		/*case GLAND_HEIGHTMAP_ROTATION_TEXT: case GLAND_HEIGHTMAP_ROTATION_PULLDOWN:*/
+		/* case GLAND_HEIGHTMAP_ROTATION_TEXT: case GLAND_HEIGHTMAP_ROTATION_PULLDOWN:*/
 			if (mode == GLWP_HEIGHTMAP) {
 				ShowDropDownMenu(w, rotation, _patches_newgame.heightmap_rotation, GLAND_HEIGHTMAP_ROTATION_PULLDOWN, 0, 0);
 			} else {
@@ -449,7 +451,7 @@ static void GenerateLandscapeWndProc(Window *w, WindowEvent *e)
 				DoCommandP(0, 3, _opt_newgame.diff.number_industries, NULL, CMD_CHANGE_DIFFICULTY_LEVEL);
 				break;
 			case GLAND_LANDSCAPE_PULLDOWN:
-			/*case GLAND_HEIGHTMAP_PULLDOWN: */
+			/* case GLAND_HEIGHTMAP_PULLDOWN: */
 				if (mode == GLWP_HEIGHTMAP) {
 					_patches_newgame.heightmap_rotation = e->we.dropdown.index;
 				} else {
diff --git a/src/gfx.cpp b/src/gfx.cpp
index 2ddf645a0..4ed1ea424 100644
--- a/src/gfx.cpp
+++ b/src/gfx.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file gfx.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -21,11 +23,11 @@
 bool _dbg_screen_rect;
 #endif
 
-byte _dirkeys;        // 1 = left, 2 = up, 4 = right, 8 = down
+byte _dirkeys;        ///< 1 = left, 2 = up, 4 = right, 8 = down
 bool _fullscreen;
 CursorVars _cursor;
-bool _ctrl_pressed;   // Is Ctrl pressed?
-bool _shift_pressed;  // Is Shift pressed?
+bool _ctrl_pressed;   ///< Is Ctrl pressed?
+bool _shift_pressed;  ///< Is Shift pressed?
 byte _fast_forward;
 bool _left_button_down;
 bool _left_button_clicked;
@@ -88,16 +90,16 @@ void GfxScroll(int left, int top, int width, int height, int xo, int yo)
 	p = _screen.pitch;
 
 	if (yo > 0) {
-		// Calculate pointers
+		/*Calculate pointers */
 		dst = _screen.dst_ptr + (top + height - 1) * p + left;
 		src = dst - yo * p;
 
-		// Decrease height and increase top
+		/* Decrease height and increase top */
 		top += yo;
 		height -= yo;
 		assert(height > 0);
 
-		// Adjust left & width
+		/* Adjust left & width */
 		if (xo >= 0) {
 			dst += xo;
 			left += xo;
@@ -113,15 +115,15 @@ void GfxScroll(int left, int top, int width, int height, int xo, int yo)
 			dst -= p;
 		}
 	} else {
-		// Calculate pointers
+		/* Calculate pointers */
 		dst = _screen.dst_ptr + top * p + left;
 		src = dst - yo * p;
 
-		// Decrese height. (yo is <=0).
+		/* Decrese height. (yo is <=0). */
 		height += yo;
 		assert(height > 0);
 
-		// Adjust left & width
+		/* Adjust left & width */
 		if (xo >= 0) {
 			dst += xo;
 			left += xo;
@@ -131,15 +133,15 @@ void GfxScroll(int left, int top, int width, int height, int xo, int yo)
 			width += xo;
 		}
 
-		// the y-displacement may be 0 therefore we have to use memmove,
-		// because source and destination may overlap
+		/* the y-displacement may be 0 therefore we have to use memmove,
+		 * because source and destination may overlap */
 		for (ht = height; ht > 0; --ht) {
 			memmove(dst, src, width);
 			src += p;
 			dst += p;
 		}
 	}
-	// This part of the screen is now dirty.
+	/* This part of the screen is now dirty. */
 	_video_driver->make_dirty(left, top, width, height);
 }
 
@@ -212,7 +214,7 @@ void GfxDrawLine(int x, int y, int x2, int y2, int color)
 	int stepy;
 	int frac;
 
-	// Check clipping first
+	/* Check clipping first */
 	{
 		DrawPixelInfo *dpi = _cur_dpi;
 		int t;
@@ -292,7 +294,7 @@ static int TruncateString(char *str, int maxw)
 			w += GetCharacterWidth(size, c);
 
 			if (w >= maxw) {
-				// string got too big... insert dotdotdot
+				/* string got too big... insert dotdotdot */
 				ddd_pos[0] = ddd_pos[1] = ddd_pos[2] = '.';
 				ddd_pos[3] = 0;
 				return ddd_w;
@@ -309,7 +311,7 @@ static int TruncateString(char *str, int maxw)
 			}
 		}
 
-		// Remember the last position where three dots fit.
+		/* Remember the last position where three dots fit. */
 		if (w + ddd < maxw) {
 			ddd_w = w + ddd;
 			ddd_pos = str;
@@ -1544,7 +1546,7 @@ void DoPaletteAnimations(void)
 	d = &_cur_palette[217];
 	memcpy(old_val, d, c * sizeof(*old_val));
 
-	// Dark blue water
+	/* Dark blue water */
 	s = (_opt.landscape == LT_CANDY) ? ev->ac : ev->a;
 	j = EXTR(320, 5);
 	for (i = 0; i != 5; i++) {
@@ -1553,7 +1555,7 @@ void DoPaletteAnimations(void)
 		if (j == 5) j = 0;
 	}
 
-	// Glittery water
+	/* Glittery water */
 	s = (_opt.landscape == LT_CANDY) ? ev->bc : ev->b;
 	j = EXTR(128, 15);
 	for (i = 0; i != 5; i++) {
@@ -1570,7 +1572,7 @@ void DoPaletteAnimations(void)
 		if (j == 5) j = 0;
 	}
 
-	// Oil refinery fire animation
+	/* Oil refinery fire animation */
 	s = ev->oil_ref;
 	j = EXTR2(512, 7);
 	for (i = 0; i != 7; i++) {
@@ -1579,7 +1581,7 @@ void DoPaletteAnimations(void)
 		if (j == 7) j = 0;
 	}
 
-	// Radio tower blinking
+	/* Radio tower blinking */
 	{
 		byte i = (_timer_counter >> 1) & 0x7F;
 		byte v;
@@ -1602,7 +1604,7 @@ void DoPaletteAnimations(void)
 		d++;
 	}
 
-	// Handle lighthouse and stadium animation
+	/* Handle lighthouse and stadium animation */
 	s = ev->lighthouse;
 	j = EXTR(256, 4);
 	for (i = 0; i != 4; i++) {
@@ -1611,9 +1613,9 @@ void DoPaletteAnimations(void)
 		if (j == 4) j = 0;
 	}
 
-	// Animate water for old DOS graphics
+	/* Animate water for old DOS graphics */
 	if (_use_dos_palette) {
-		// Dark blue water DOS
+		/* Dark blue water DOS */
 		s = (_opt.landscape == LT_CANDY) ? ev->ac : ev->a;
 		j = EXTR(320, 5);
 		for (i = 0; i != 5; i++) {
@@ -1622,7 +1624,7 @@ void DoPaletteAnimations(void)
 			if (j == 5) j = 0;
 		}
 
-		// Glittery water DOS
+		/* Glittery water DOS */
 		s = (_opt.landscape == LT_CANDY) ? ev->bc : ev->b;
 		j = EXTR(128, 15);
 		for (i = 0; i != 5; i++) {
@@ -1670,11 +1672,11 @@ byte GetCharacterWidth(FontSize size, WChar key)
 
 void ScreenSizeChanged(void)
 {
-	// check the dirty rect
+	/* check the dirty rect */
 	if (_invalid_rect.right >= _screen.width) _invalid_rect.right = _screen.width;
 	if (_invalid_rect.bottom >= _screen.height) _invalid_rect.bottom = _screen.height;
 
-	// screen size changed and the old bitmap is invalid now, so we don't want to undraw it
+	/* screen size changed and the old bitmap is invalid now, so we don't want to undraw it */
 	_cursor.visible = false;
 }
 
@@ -1701,7 +1703,7 @@ void DrawMouseCursor(void)
 	/* Redraw mouse cursor but only when it's inside the window */
 	if (!_cursor.in_window) return;
 
-	// Don't draw the mouse cursor if it's already drawn
+	/* Don't draw the mouse cursor if it's already drawn */
 	if (_cursor.visible) {
 		if (!_cursor.dirty) return;
 		UndrawMouseCursor();
@@ -1731,13 +1733,13 @@ void DrawMouseCursor(void)
 
 	assert(w * h < (int)sizeof(_cursor_backup));
 
-	// Make backup of stuff below cursor
+	/* Make backup of stuff below cursor */
 	memcpy_pitch(
 		_cursor_backup,
 		_screen.dst_ptr + _cursor.draw_pos.x + _cursor.draw_pos.y * _screen.pitch,
 		_cursor.draw_size.x, _cursor.draw_size.y, _screen.pitch, _cursor.draw_size.x);
 
-	// Draw cursor on screen
+	/* Draw cursor on screen */
 	_cur_dpi = &_screen;
 	DrawSprite(_cursor.sprite, _cursor.pal, _cursor.pos.x, _cursor.pos.y);
 
@@ -1806,14 +1808,14 @@ void DrawDirtyBlocks(void)
 				byte *p = b;
 				int h2;
 
-				// First try coalescing downwards
+				/* First try coalescing downwards */
 				do {
 					*p = 0;
 					p += DIRTY_BYTES_PER_LINE;
 					bottom += 8;
 				} while (bottom != h && *p != 0);
 
-				// Try coalescing to the right too.
+				/* Try coalescing to the right too. */
 				h2 = (bottom - y) >> 3;
 				assert(h2 > 0);
 				p = b;
@@ -1821,14 +1823,14 @@ void DrawDirtyBlocks(void)
 				while (right != w) {
 					byte *p2 = ++p;
 					int h = h2;
-					// Check if a full line of dirty flags is set.
+					/* Check if a full line of dirty flags is set. */
 					do {
 						if (!*p2) goto no_more_coalesc;
 						p2 += DIRTY_BYTES_PER_LINE;
 					} while (--h != 0);
 
-					// Wohoo, can combine it one step to the right!
-					// Do that, and clear the bits.
+					/* Wohoo, can combine it one step to the right!
+					 * Do that, and clear the bits. */
 					right += 64;
 
 					h = h2;
@@ -2005,9 +2007,9 @@ void CursorTick(void)
 
 void SetMouseCursor(SpriteID sprite, SpriteID pal)
 {
-	// Turn off animation
+	/* Turn off animation */
 	_cursor.animate_timeout = 0;
-	// Set cursor
+	/* Set cursor */
 	SetCursorSprite(sprite, pal);
 }
 
diff --git a/src/gfx.h b/src/gfx.h
index ab7a1c1ee..f4f2d6a88 100644
--- a/src/gfx.h
+++ b/src/gfx.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file gfx.h */
+
 #ifndef GFX_H
 #define GFX_H
 
@@ -10,7 +12,7 @@ enum WindowKeyCodes {
 	WKC_ALT   = 0x2000,
 	WKC_META  = 0x1000,
 
-	// Special ones
+	/* Special ones */
 	WKC_NONE        =  0,
 	WKC_ESC         =  1,
 	WKC_BACKSPACE   =  2,
@@ -22,17 +24,17 @@ enum WindowKeyCodes {
 	WKC_END         =  7,
 	WKC_HOME        =  8,
 
-	// Arrow keys
+	/* Arrow keys */
 	WKC_LEFT        =  9,
 	WKC_UP          = 10,
 	WKC_RIGHT       = 11,
 	WKC_DOWN        = 12,
 
-	// Return & tab
+	/* Return & tab */
 	WKC_RETURN      = 13,
 	WKC_TAB         = 14,
 
-	// Numerical keyboard
+	/* Numerical keyboard */
 	WKC_NUM_0       = 16,
 	WKC_NUM_1       = 17,
 	WKC_NUM_2       = 18,
@@ -50,10 +52,10 @@ enum WindowKeyCodes {
 	WKC_NUM_ENTER   = 30,
 	WKC_NUM_DECIMAL = 31,
 
-	// Space
+	/* Space */
 	WKC_SPACE       = 32,
 
-	// Function keys
+	/* Function keys */
 	WKC_F1          = 33,
 	WKC_F2          = 34,
 	WKC_F3          = 35,
@@ -67,15 +69,15 @@ enum WindowKeyCodes {
 	WKC_F11         = 43,
 	WKC_F12         = 44,
 
-	// backquote is the key left of "1"
-	// we only store this key here, no matter what character is really mapped to it
-	// on a particular keyboard. (US keyboard: ` and ~ ; German keyboard: ^ and °)
+	/* backquote is the key left of "1"
+	 * we only store this key here, no matter what character is really mapped to it
+	 * on a particular keyboard. (US keyboard: ` and ~ ; German keyboard: ^ and °) */
 	WKC_BACKQUOTE   = 45,
 	WKC_PAUSE       = 46,
 
-	// 0-9 are mapped to 48-57
-	// A-Z are mapped to 65-90
-	// a-z are mapped to 97-122
+	/* 0-9 are mapped to 48-57
+	 * A-Z are mapped to 65-90
+	 * a-z are mapped to 97-122 */
 };
 
 enum GameModes {
@@ -138,11 +140,11 @@ typedef struct Colour {
 
 
 
-extern byte _dirkeys;        // 1 = left, 2 = up, 4 = right, 8 = down
+extern byte _dirkeys;        ///< 1 = left, 2 = up, 4 = right, 8 = down
 extern bool _fullscreen;
 extern CursorVars _cursor;
-extern bool _ctrl_pressed;   // Is Ctrl pressed?
-extern bool _shift_pressed;  // Is Shift pressed?
+extern bool _ctrl_pressed;   ///< Is Ctrl pressed?
+extern bool _shift_pressed;  ///< Is Shift pressed?
 extern byte _fast_forward;
 
 extern bool _left_button_down;
@@ -168,7 +170,7 @@ void HandleMouseEvents(void);
 void CSleep(int milliseconds);
 void UpdateWindows(void);
 
-uint32 InteractiveRandom(void); /* Used for random sequences that are not the same on the other end of the multiplayer link */
+uint32 InteractiveRandom(void); //< Used for random sequences that are not the same on the other end of the multiplayer link
 uint InteractiveRandomRange(uint max);
 void DrawTextMessage(void);
 void DrawMouseCursor(void);
@@ -192,8 +194,8 @@ void RedrawScreenRect(int left, int top, int right, int bottom);
 void GfxScroll(int left, int top, int width, int height, int xo, int yo);
 
 
-// XXX doesn't really belong here, but the only
-// consumers always use it in conjunction with DoDrawString()
+/* XXX doesn't really belong here, but the only
+ * consumers always use it in conjunction with DoDrawString() */
 #define UPARROW   "\xEE\x8A\x80"
 #define DOWNARROW "\xEE\x8A\xAA"
 
@@ -231,7 +233,7 @@ void GfxInitPalettes(void);
 
 bool FillDrawPixelInfo(DrawPixelInfo* n, int left, int top, int width, int height);
 
-/* window.c */
+/* window.cpp */
 void DrawOverlappedWindowForAll(int left, int top, int right, int bottom);
 
 void SetMouseCursor(CursorID cursor);
@@ -245,7 +247,7 @@ bool ChangeResInGame(int w, int h);
 void SortResolutions(int count);
 void ToggleFullScreen(bool fs);
 
-/* gfx.c */
+/* gfx.cpp */
 #define ASCII_LETTERSTART 32
 extern FontSize _cur_fontsize;
 
@@ -291,7 +293,7 @@ VARDEF byte _colour_gradient[16][8];
 VARDEF bool _use_dos_palette;
 
 typedef enum StringColorFlags {
-	IS_PALETTE_COLOR = 0x100, // color value is already a real palette color index, not an index of a StringColor
+	IS_PALETTE_COLOR = 0x100, ///< color value is already a real palette color index, not an index of a StringColor
 } StringColorFlags;
 
 
diff --git a/src/gfxinit.cpp b/src/gfxinit.cpp
index fbf7f4b89..6dc798edb 100644
--- a/src/gfxinit.cpp
+++ b/src/gfxinit.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file gfxinit.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -17,13 +19,13 @@
 #include <string.h>
 
 typedef struct MD5File {
-	const char * filename;     // filename
-	md5_byte_t hash[16]; // md5 sum of the file
+	const char * filename;     ///< filename
+	md5_byte_t hash[16];       ///< md5 sum of the file
 } MD5File;
 
 typedef struct FileList {
-	MD5File basic[4];     // grf files that always have to be loaded
-	MD5File landscape[3]; // landscape specific grf files
+	MD5File basic[4];          ///< grf files that always have to be loaded
+	MD5File landscape[3];      ///< landscape specific grf files
 } FileList;
 
 enum {
@@ -110,7 +112,7 @@ static bool FileMD5(const MD5File file, bool warn)
 	FILE *f;
 	char buf[MAX_PATH];
 
-	// open file
+	/* open file */
 	snprintf(buf, lengthof(buf), "%s%s", _paths.data_dir, file.filename);
 	f = fopen(buf, "rb");
 
@@ -163,7 +165,7 @@ static bool FileMD5(const MD5File file, bool warn)
 void CheckExternalFiles(void)
 {
 	uint i;
-	// count of files from this version
+	/* count of files from this version */
 	uint dos = 0;
 	uint win = 0;
 
@@ -202,58 +204,58 @@ void CheckExternalFiles(void)
 
 
 static const SpriteID trg1idx[] = {
-	   0,    1, // Mouse cursor, ZZZ
+	   0,    1, ///< Mouse cursor, ZZZ
 /* Medium font */
-	   2,   92, // ' ' till 'z'
+	   2,   92, ///< ' ' till 'z'
 	SKIP,   36,
-	 160,  160, // Move ¾ to the correct position
-	  98,   98, // Up arrow
+	 160,  160, ///< Move ¾ to the correct position
+	  98,   98, ///< Up arrow
 	 131,  133,
-	SKIP,    1, // skip currency sign
+	SKIP,    1, ///< skip currency sign
 	 135,  135,
 	SKIP,    1,
 	 137,  137,
 	SKIP,    1,
 	 139,  139,
-	 140,  140, // TODO Down arrow
+	 140,  140, ///< @todo Down arrow
 	 141,  141,
-	 142,  142, // TODO Check mark
-	 143,  143, // TODO Cross
+	 142,  142, ///< @todo Check mark
+	 143,  143, ///< @todo Cross
 	 144,  144,
-	 145,  145, // TODO Right arrow
+	 145,  145, ///< @todo Right arrow
 	 146,  149,
-	 118,  122, // Transport markers
+	 118,  122, ///< Transport markers
 	SKIP,    2,
 	 157,  157,
-	 114,  115, // Small up/down arrows
+	 114,  115, ///< Small up/down arrows
 	SKIP,    1,
 	 161,  225,
 /* Small font */
-	 226,  316, // ' ' till 'z'
+	 226,  316, ///< ' ' till 'z'
 	SKIP,   36,
-	 384,  384, // Move ¾ to the correct position
-	 322,  322, // Up arrow
+	 384,  384, ///< Move ¾ to the correct position
+	 322,  322, ///< Up arrow
 	 355,  357,
-	SKIP,    1, // skip currency sign
+	SKIP,    1, ///< skip currency sign
 	 359,  359,
 	SKIP,    1,
 	 361,  361,
 	SKIP,    1,
 	 363,  363,
-	 364,  364, // TODO Down arrow
+	 364,  364, ////< @todo Down arrow
 	 365,  366,
 	SKIP,    1,
 	 368,  368,
-	 369,  369, // TODO Right arrow
+	 369,  369, ///< @todo Right arrow
 	 370,  373,
 	SKIP,    7,
 	 381,  381,
 	SKIP,    3,
 	 385,  449,
 /* Big font */
-	 450,  540, // ' ' till 'z'
+	 450,  540, ///< ' ' till 'z'
 	SKIP,   36,
-	 608,  608, // Move ¾ to the correct position
+	 608,  608, ///< Move ¾ to the correct position
 	SKIP,    1,
 	 579,  581,
 	SKIP,    1,
@@ -288,51 +290,51 @@ static const SpriteID trg1idx[] = {
  * a maximum use of sprite slots. */
 static const SpriteID _openttd_grf_indexes[] = {
 	SPR_IMG_AUTORAIL, SPR_CURSOR_WAYPOINT, // icons etc
-	134, 134,  // euro symbol medium size
-	582, 582,  // euro symbol large size
-	358, 358,  // euro symbol tiny
+	134, 134,  ///< euro symbol medium size
+	582, 582,  ///<  euro symbol large size
+	358, 358,  ///<  euro symbol tiny
 	SPR_CURSOR_CANAL, SPR_IMG_FASTFORWARD, // more icons
-	648, 648, // nordic char: æ
-	616, 616, // nordic char: Æ
-	666, 666, // nordic char: ø
-	634, 634, // nordic char: Ø
+	648, 648, ///<  nordic char: æ
+	616, 616, ///<  nordic char: Æ
+	666, 666, ///<  nordic char: ø
+	634, 634, ///<  nordic char: Ø
 	SPR_PIN_UP, SPR_CURSOR_CLONE_TRAIN, // more icons
-	382, 383, // ¼ ½ tiny
-	158, 159, // ¼ ½ medium
-	606, 607, // ¼ ½ large
-	360, 360, // ¦ tiny
-	362, 362, // ¨ tiny
-	136, 136, // ¦ medium
-	138, 138, // ¨ medium
-	584, 584, // ¦ large
-	586, 586, // ¨ large
-	626, 626, // Ð large
-	658, 658, // ð large
-	374, 374, // ´ tiny
-	378, 378, // ¸ tiny
-	150, 150, // ´ medium
-	154, 154, // ¸ medium
-	598, 598, // ´ large
-	602, 602, // ¸ large
-	640, 640, // Þ large
-	672, 672, // þ large
-	380, 380, // º tiny
-	156, 156, // º medium
-	604, 604, // º large
-	317, 320, // { | } ~ tiny
-	 93,  96, // { | } ~ medium
-	541, 544, // { | } ~ large
+	382, 383, ///<  ¼ ½ tiny
+	158, 159, ///<  ¼ ½ medium
+	606, 607, ///<  ¼ ½ large
+	360, 360, ///<  ¦ tiny
+	362, 362, ///<  ¨ tiny
+	136, 136, ///<  ¦ medium
+	138, 138, ///<  ¨ medium
+	584, 584, ///<  ¦ large
+	586, 586, ///<  ¨ large
+	626, 626, ///<  Ð large
+	658, 658, ///<  ð large
+	374, 374, ///<  ´ tiny
+	378, 378, ///<  ¸ tiny
+	150, 150, ///<  ´ medium
+	154, 154, ///<  ¸ medium
+	598, 598, ///<  ´ large
+	602, 602, ///<  ¸ large
+	640, 640, ///<  Þ large
+	672, 672, ///<  þ large
+	380, 380, ///<  º tiny
+	156, 156, ///<  º medium
+	604, 604, ///<  º large
+	317, 320, ///<  { | } ~ tiny
+	 93,  96, ///<  { | } ~ medium
+	541, 544, ///<  { | } ~ large
 	SPR_HOUSE_ICON, SPR_HOUSE_ICON,
-	585, 585, // § large
-	587, 587, // © large
-	592, 592, // ® large
-	594, 597, // ° ± ² ³ large
-	633, 633, // × large
-	665, 665, // ÷ large
+	585, 585, ///<  § large
+	587, 587, ///<  © large
+	592, 592, ///<  ® large
+	594, 597, ///<  ° ± ² ³ large
+	633, 633, ///<  × large
+	665, 665, ///<  ÷ large
 	SPR_SELL_TRAIN, SPR_SHARED_ORDERS_ICON,
-	377, 377, // · small
-	153, 153, // · medium
-	601, 601, // · large
+	377, 377, ///<  · small
+	153, 153, ///<  · medium
+	601, 601, ///<  · large
 	SPR_WARNING_SIGN, SPR_WARNING_SIGN,
 	END
 };
diff --git a/src/gfxinit.h b/src/gfxinit.h
index d3873ff23..1d5de2fac 100644
--- a/src/gfxinit.h
+++ b/src/gfxinit.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file gfxinit.h */
+
 #ifndef GFXINIT_H
 #define GFXINIT_H
 
diff --git a/src/graph_gui.cpp b/src/graph_gui.cpp
index 6f5693347..f123e58ff 100644
--- a/src/graph_gui.cpp
+++ b/src/graph_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file graph_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
@@ -28,13 +30,13 @@ enum {
 	GRAPH_AXIS_LABEL_COLOUR = 16,
 	GRAPH_AXIS_LINE_COLOUR  = 215,
 
-	GRAPH_X_POSITION_BEGINNING  = 44,  // Start the graph 44 pixels from gw->left
-	GRAPH_X_POSITION_SEPARATION = 22,  // There are 22 pixels between each X value
+	GRAPH_X_POSITION_BEGINNING  = 44,  ///< Start the graph 44 pixels from gw->left
+	GRAPH_X_POSITION_SEPARATION = 22,  ///< There are 22 pixels between each X value
 
-	/* How many horizontal lines to draw. 9 is convenient as that means the
-	 * distance between them is the height of the graph / 8, which is the same
+	GRAPH_NUM_LINES_Y = 9, ///< How many horizontal lines to draw.
+	/* 9 is convenient as that means the distance between them is the height of the graph / 8,
+	 * which is the same
 	 * as height >> 3. */
-	GRAPH_NUM_LINES_Y = 9,
 };
 
 /* Apparently these don't play well with enums. */
@@ -42,7 +44,7 @@ static const int64 INVALID_DATAPOINT     = INT64_MAX; // Value used for a datapo
 static const uint  INVALID_DATAPOINT_POS = UINT_MAX;  // Used to determine if the previous point was drawn.
 
 typedef struct GraphDrawer {
-	uint excluded_data; // bitmask of the datasets that shouldn't be displayed.
+	uint excluded_data; ///< bitmask of the datasets that shouldn't be displayed.
 	byte num_dataset;
 	byte num_on_x_axis;
 	bool has_negative_values;
@@ -58,18 +60,18 @@ typedef struct GraphDrawer {
 	uint16 x_values_start;
 	uint16 x_values_increment;
 
-	int left, top;  // Where to start drawing the graph, in pixels.
-	uint height;    // The height of the graph in pixels.
+	int left, top;  ///< Where to start drawing the graph, in pixels.
+	uint height;    ///< The height of the graph in pixels.
 	StringID format_str_y_axis;
 	byte colors[GRAPH_MAX_DATASETS];
-	int64 cost[GRAPH_MAX_DATASETS][24]; // last 2 years
+	int64 cost[GRAPH_MAX_DATASETS][24]; ///< last 2 years
 } GraphDrawer;
 
 static void DrawGraph(const GraphDrawer *gw)
 {
-	uint x, y;            // Reused whenever x and y coordinates are needed.
-	int64 highest_value;  // Highest value to be drawn.
-	int x_axis_offset;    // Distance from the top of the graph to the x axis.
+	uint x, y;            ///< Reused whenever x and y coordinates are needed.
+	int64 highest_value;  ///< Highest value to be drawn.
+	int x_axis_offset;    ///< Distance from the top of the graph to the x axis.
 
 	/* the colors and cost array of GraphDrawer must accomodate
 	 * both values for cargo and players. So if any are higher, quit */
@@ -330,7 +332,7 @@ static void SetupGraphDrawerForPlayers(GraphDrawer *gd)
 	byte nums;
 	int mo,yr;
 
-	// Exclude the players which aren't valid
+	/* Exclude the players which aren't valid */
 	FOR_ALL_PLAYERS(p) {
 		if (!p->is_active) SETBIT(excluded_players, p->index);
 	}
@@ -920,7 +922,7 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 			int total_score = 0;
 			int color_done, color_notdone;
 
-			// Draw standard stuff
+			/* Draw standard stuff */
 			DrawWindowWidgets(w);
 
 			/* Check if the currently selected player is still active. */
@@ -949,25 +951,25 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 			/* If there are no active players, don't display anything else. */
 			if (_performance_rating_detail_player == INVALID_PLAYER) break;
 
-			// Paint the player icons
+			/* Paint the player icons */
 			for (PlayerID i = PLAYER_FIRST; i < MAX_PLAYERS; i++) {
 				if (!GetPlayer(i)->is_active) {
-					// Check if we have the player as an active player
+					/* Check if we have the player as an active player */
 					if (!IsWindowWidgetDisabled(w, i + 13)) {
-						// Bah, player gone :(
+						/* Bah, player gone :( */
 						DisableWindowWidget(w, i + 13);
 
-						// We need a repaint
+						/* We need a repaint */
 						SetWindowDirty(w);
 					}
 					continue;
 				}
 
-				// Check if we have the player marked as inactive
+				/* Check if we have the player marked as inactive */
 				if (IsWindowWidgetDisabled(w, i + 13)) {
-					// New player! Yippie :p
+					/* New player! Yippie :p */
 					EnableWindowWidget(w, i + 13);
-					// We need a repaint
+					/* We need a repaint */
 					SetWindowDirty(w);
 				}
 
@@ -975,18 +977,18 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 				DrawPlayerIcon(i, i * 37 + 13 + x, 16 + x);
 			}
 
-			// The colors used to show how the progress is going
+			/* The colors used to show how the progress is going */
 			color_done = _colour_gradient[COLOUR_GREEN][4];
 			color_notdone = _colour_gradient[COLOUR_RED][4];
 
-			// Draw all the score parts
+			/* Draw all the score parts */
 			for (ScoreID i = SCORE_BEGIN; i < SCORE_END; i++) {
 				int val    = _score_part[_performance_rating_detail_player][i];
 				int needed = _score_info[i].needed;
 				int score  = _score_info[i].score;
 
 				y += 20;
-				// SCORE_TOTAL has his own rulez ;)
+				/* SCORE_TOTAL has his own rulez ;) */
 				if (i == SCORE_TOTAL) {
 					needed = total_score;
 					score = SCORE_MAX;
@@ -996,11 +998,11 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 
 				DrawString(7, y, STR_PERFORMANCE_DETAIL_VEHICLES + i, 0);
 
-				// Draw the score
+				/* Draw the score */
 				SetDParam(0, score);
 				DrawStringRightAligned(107, y, SET_PERFORMANCE_DETAIL_INT, 0);
 
-				// Calculate the %-bar
+				/* Calculate the %-bar */
 				if (val > needed) {
 					x = 50;
 				} else if (val == 0) {
@@ -1009,28 +1011,28 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 					x = val * 50 / needed;
 				}
 
-				// SCORE_LOAN is inversed
+				/* SCORE_LOAN is inversed */
 				if (val < 0 && i == SCORE_LOAN) x = 0;
 
-				// Draw the bar
+				/* Draw the bar */
 				if (x !=  0) GfxFillRect(112,     y - 2, 112 + x,  y + 10, color_done);
 				if (x != 50) GfxFillRect(112 + x, y - 2, 112 + 50, y + 10, color_notdone);
 
-				// Calculate the %
+				/* Calculate the % */
 				x = (val <= needed) ? val * 100 / needed : 100;
 
-				// SCORE_LOAN is inversed
+				/* SCORE_LOAN is inversed */
 				if (val < 0 && i == SCORE_LOAN) x = 0;
 
-				// Draw it
+				/* Draw it */
 				SetDParam(0, x);
 				DrawStringCentered(137, y, STR_PERFORMANCE_DETAIL_PERCENT, 0);
 
-				// SCORE_LOAN is inversed
+				/* SCORE_LOAN is inversed */
 				if (i == SCORE_LOAN) val = needed - val;
 
-				// Draw the amount we have against what is needed
-				//  For some of them it is in currency format
+				/* Draw the amount we have against what is needed
+				 * For some of them it is in currency format */
 				SetDParam(0, val);
 				SetDParam(1, needed);
 				switch (i) {
@@ -1050,9 +1052,9 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 		}
 
 		case WE_CLICK:
-			// Check which button is clicked
+			/* Check which button is clicked */
 			if (IS_INT_INSIDE(e->we.click.widget, 13, 21)) {
-				// Is it no on disable?
+				/* Is it no on disable? */
 				if (!IsWindowWidgetDisabled(w, e->we.click.widget)) {
 					RaiseWindowWidget(w, _performance_rating_detail_player + 13);
 					_performance_rating_detail_player = (PlayerID)(e->we.click.widget - 13);
@@ -1086,7 +1088,7 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 		}
 
 		case WE_TICK: {
-			// Update the player score every 5 days
+			/* Update the player score every 5 days */
 			if (--w->custom[0] == 0) {
 				w->custom[0] = DAY_TICKS;
 				if (--w->custom[1] == 0) {
@@ -1094,7 +1096,7 @@ static void PerformanceRatingDetailWndProc(Window *w, WindowEvent *e)
 
 					w->custom[1] = 5;
 					FOR_ALL_PLAYERS(p2) {
-						// Skip if player is not active
+						/* Skip if player is not active */
 						if (p2->is_active) UpdateCompanyRatingAndValue(p2, false);
 					}
 					SetWindowDirty(w);
diff --git a/src/gui.h b/src/gui.h
index 3559078b3..050e51c98 100644
--- a/src/gui.h
+++ b/src/gui.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file gui.h */
+
 #ifndef GUI_H
 #define GUI_H
 
@@ -7,19 +9,19 @@
 #include "window.h"
 #include "string.h"
 
-/* main_gui.c */
+/* main_gui.cpp */
 void SetupColorsAndInitialWindow(void);
 void CcPlaySound10(bool success, TileIndex tile, uint32 p1, uint32 p2);
 void CcBuildCanal(bool success, TileIndex tile, uint32 p1, uint32 p2);
 void CcTerraform(bool success, TileIndex tile, uint32 p1, uint32 p2);
 
-/* settings_gui.c */
+/* settings_gui.cpp */
 void ShowGameOptions(void);
 void ShowGameDifficulty(void);
 void ShowPatchesSelection(void);
 void DrawArrowButtons(int x, int y, int ctab, byte state, bool clickable_left, bool clickable_right);
 
-/* graph_gui.c */
+/* graph_gui.cpp */
 void ShowOperatingProfitGraph(void);
 void ShowIncomeGraph(void);
 void ShowDeliveredCargoGraph(void);
@@ -29,36 +31,36 @@ void ShowCargoPaymentRates(void);
 void ShowCompanyLeagueTable(void);
 void ShowPerformanceRatingDetail(void);
 
-/* news_gui.c */
+/* news_gui.cpp */
 void ShowLastNewsMessage(void);
 void ShowMessageOptions(void);
 void ShowMessageHistory(void);
 
-/* rail_gui.c */
+/* rail_gui.cpp */
 void ShowBuildRailToolbar(RailType railtype, int button);
 void PlaceProc_BuyLand(TileIndex tile);
 void ReinitGuiAfterToggleElrail(bool disable);
 
-/* train_gui.c */
+/* train_gui.cpp */
 void ShowTrainViewWindow(const Vehicle *v);
 void ShowOrdersWindow(const Vehicle *v);
 
-/* road_gui.c */
+/* road_gui.cpp */
 void ShowBuildRoadToolbar(void);
 void ShowBuildRoadScenToolbar(void);
 void ShowRoadVehViewWindow(const Vehicle *v);
 
-/* dock_gui.c */
+/* dock_gui.cpp */
 void ShowBuildDocksToolbar(void);
 void ShowShipViewWindow(const Vehicle *v);
 
-/* aircraft_gui.c */
+/* aircraft_gui.cpp */
 void ShowBuildAirToolbar(void);
 
-/* terraform_gui.c */
+/* terraform_gui.cpp */
 void ShowTerraformToolbar(Window *link = NULL);
 
-/* tgp_gui.c */
+/* tgp_gui.cpp */
 void ShowGenerateLandscape(void);
 void ShowHeightmapLoad(void);
 
@@ -75,7 +77,7 @@ enum { // max 32 - 4 = 28 types
 	GUI_PlaceProc_RockyArea       = 5 << 4,
 };
 
-/* misc_gui.c */
+/* misc_gui.cpp */
 void PlaceLandBlockInfo(void);
 void ShowAboutWindow(void);
 void ShowBuildTreesToolbar(void);
@@ -120,7 +122,7 @@ void SetFiosType(const byte fiostype);
 /* FIOS_TYPE_FILE, FIOS_TYPE_OLDFILE etc. different colours */
 extern const byte _fios_colors[];
 
-/* bridge_gui.c */
+/* bridge_gui.cpp */
 void ShowBuildBridgeWindow(uint start, uint end, byte type);
 
 void ShowBuildIndustryWindow(void);
@@ -128,12 +130,12 @@ void ShowQueryString(StringID str, StringID caption, uint maxlen, uint maxwidth,
 void ShowQuery(StringID caption, StringID message, Window *w, void (*callback)(Window*, bool));
 void ShowMusicWindow(void);
 
-/* main_gui.c */
+/* main_gui.cpp */
 void HandleOnEditText(const char *str);
 VARDEF bool _station_show_coverage;
 VARDEF PlaceProc *_place_proc;
 
-/* vehicle_gui.c */
+/* vehicle_gui.cpp */
 void InitializeGUI(void);
 
 #endif /* GUI_H */
diff --git a/src/hal.h b/src/hal.h
index 0729c6c99..b9494f089 100644
--- a/src/hal.h
+++ b/src/hal.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file hal.h Hardware Abstraction Layer declarations */
+
 #ifndef HAL_H
 #define HAL_H
 
diff --git a/src/heightmap.cpp b/src/heightmap.cpp
index 0e80ca2b9..6fb0bfe4c 100644
--- a/src/heightmap.cpp
+++ b/src/heightmap.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file heightmap.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "variables.h"
@@ -226,7 +228,7 @@ static bool ReadHeightmapBMP(char *filename, uint *x, uint *y, byte **map)
 	BmpData data;
 	BmpBuffer buffer;
 
-	// Init BmpData
+	/* Init BmpData */
 	memset(&data, 0, sizeof(data));
 
 	f = fopen(filename, "rb");
diff --git a/src/heightmap.h b/src/heightmap.h
index d7592bf27..5cf66e7ce 100644
--- a/src/heightmap.h
+++ b/src/heightmap.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file heightmap.h */
+
 #ifndef HEIGHTMAP_H
 #define HEIGHTMAP_H
 
@@ -8,12 +10,15 @@
  * Otherwise you will get inconsistent behaviour.
  */
 enum {
-	HM_COUNTER_CLOCKWISE, //! Rotate the map counter clockwise 45 degrees
-	HM_CLOCKWISE,         //! Rotate the map clockwise 45 degrees
+	HM_COUNTER_CLOCKWISE, ///< Rotate the map counter clockwise 45 degrees
+	HM_CLOCKWISE,         ///< Rotate the map clockwise 45 degrees
 };
 
 /**
  * Get the dimensions of a heightmap.
+ * @param filename to query
+ * @param x dimension x
+ * @param y dimension y
  * @return Returns false if loading of the image failed.
  */
 bool GetHeightmapDimensions(char *filename, uint *x, uint *y);
@@ -22,11 +27,13 @@ bool GetHeightmapDimensions(char *filename, uint *x, uint *y);
  * Load a heightmap from file and change the map in his current dimensions
  *  to a landscape representing the heightmap.
  * It converts pixels to height. The brighter, the higher.
+ * @param filename of the heighmap file to be imported
  */
 void LoadHeightmap(char *filename);
 
 /**
  * Make an empty world where all tiles are of height 'tile_height'.
+ * @param tile_height of the desired new empty world
  */
 void FlatEmptyWorld(byte tile_height);
 
diff --git a/src/helpers.cpp b/src/helpers.cpp
index 941906a60..c898003a6 100644
--- a/src/helpers.cpp
+++ b/src/helpers.cpp
@@ -1,4 +1,7 @@
 /* $Id$ */
+
+/** @file helpers.cpp */
+
 #include "stdafx.h"
 
 #include "openttd.h"
@@ -12,51 +15,74 @@
 /* we cannot expose CBlobT directly to C so we must cast EngineList* to CBlobT<EngineID>* always when we are called from C */
 #define B (*(CBlobT<EngineID>*)el)
 
-/** Create Engine List (and initialize it to empty) */
+/** Create Engine List (and initialize it to empty)
+ * @param el list to be created
+ */
 void EngList_Create(EngineList *el)
 {
-	// call CBlobT constructor explicitly
+	/* call CBlobT constructor explicitly */
 	new (&B) CBlobT<EngineID>();
 }
 
-/** Destroy Engine List (and free its contents) */
+/** Destroy Engine List (and free its contents)
+ * @param el list to be destroyed
+ */
 void EngList_Destroy(EngineList *el)
 {
-	// call CBlobT destructor explicitly
+	/* call CBlobT destructor explicitly */
 	B.~CBlobT<EngineID>();
 }
 
-/** Return number of items stored in the Engine List */
+/** Return number of items stored in the Engine List
+ * @param el list for count inquiry
+ * @return the desired count
+ */
 uint EngList_Count(const EngineList *el)
 {
 	return B.Size();
 }
 
-/** Add new item at the end of Engine List */
+/** Add new item at the end of Engine List
+ * @param el list o which to add an engine
+ * @param eif engine to add to the list
+ */
 void EngList_Add(EngineList *el, EngineID eid)
 {
 	B.Append(eid);
 }
 
-/** Return pointer to the items array held by Engine List */
+/** Return pointer to the items array held by Engine List
+ * @param el list from which the array pointer has to be returned
+ * @return the pointer required
+ */
 EngineID* EngList_Items(EngineList *el)
 {
 	return B.Data();
 }
 
-/** Clear the Engine List (by invalidating all its items == reseting item count to zero) */
+/** Clear the Engine List (by invalidating all its items == reseting item count to zero)
+ * @param el list to be cleared
+ */
 void EngList_RemoveAll(EngineList *el)
 {
 	B.Clear();
 }
 
-/** Sort all items using qsort() and given 'CompareItems' function */
+/** Sort all items using qsort() and given 'CompareItems' function
+ * @param el list to be sorted
+ * @param compare function for evaluation of the quicksort
+ */
 void EngList_Sort(EngineList *el, EngList_SortTypeFunction compare)
 {
 	qsort(B.Data(), B.Size(), sizeof(**el), compare);
 }
 
-/** Sort selected range of items (on indices @ <begin, begin+num_items-1>) */
+/** Sort selected range of items (on indices @ <begin, begin+num_items-1>)
+ * @param el list to be sorted
+ * @param compare function for evaluation of the quicksort
+ * @param begin start of sorting
+ * @param count of items to be sorted
+ */
 void EngList_SortPartial(EngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items)
 {
 	assert(begin <= (uint)B.Size());
diff --git a/src/helpers.hpp b/src/helpers.hpp
index 9f4cf0c82..c3f7f7930 100644
--- a/src/helpers.hpp
+++ b/src/helpers.hpp
@@ -1,9 +1,10 @@
 /* $Id$ */
 
+/** @file helpers.hpp */
+
 #ifndef HELPERS_HPP
 #define HELPERS_HPP
 
-/** @file helpers.hpp */
 #include "macros.h"
 
 /** When allocating using malloc/calloc in C++ it is usually needed to cast the return value
diff --git a/src/window.h b/src/window.h
index 8d893ffd1..2ff66de35 100644
--- a/src/window.h
+++ b/src/window.h
@@ -43,19 +43,19 @@ typedef void WindowProc(Window *w, WindowEvent *e);
    That was all.. good luck, and enjoy :) -- TrueLight */
 
 typedef enum ResizeFlags {
-	RESIZE_NONE   = 0,
+	RESIZE_NONE   = 0,  ///< no resize required
 
-	RESIZE_LEFT   = 1,
-	RESIZE_RIGHT  = 2,
-	RESIZE_TOP    = 4,
-	RESIZE_BOTTOM = 8,
+	RESIZE_LEFT   = 1,  ///< left resize flag
+	RESIZE_RIGHT  = 2,  ///< rigth resize flag
+	RESIZE_TOP    = 4,  ///< top resize flag
+	RESIZE_BOTTOM = 8,  ///< bottom resize flag
 
-	RESIZE_LR     = RESIZE_LEFT  | RESIZE_RIGHT,
-	RESIZE_RB     = RESIZE_RIGHT | RESIZE_BOTTOM,
-	RESIZE_TB     = RESIZE_TOP   | RESIZE_BOTTOM,
-	RESIZE_LRB    = RESIZE_LEFT  | RESIZE_RIGHT  | RESIZE_BOTTOM,
-	RESIZE_LRTB   = RESIZE_LEFT  | RESIZE_RIGHT  | RESIZE_TOP | RESIZE_BOTTOM,
-	RESIZE_RTB    = RESIZE_RIGHT | RESIZE_TOP    | RESIZE_BOTTOM,
+	RESIZE_LR     = RESIZE_LEFT  | RESIZE_RIGHT,   ///<  combination of left and right resize flags
+	RESIZE_RB     = RESIZE_RIGHT | RESIZE_BOTTOM,  ///<  combination of right and bottom resize flags
+	RESIZE_TB     = RESIZE_TOP   | RESIZE_BOTTOM,  ///<  combination of top and bottom resize flags
+	RESIZE_LRB    = RESIZE_LEFT  | RESIZE_RIGHT  | RESIZE_BOTTOM, ///< combination of left, right and bottom resize flags
+	RESIZE_LRTB   = RESIZE_LEFT  | RESIZE_RIGHT  | RESIZE_TOP | RESIZE_BOTTOM,  ///<  combination of all resize flags
+	RESIZE_RTB    = RESIZE_RIGHT | RESIZE_TOP    | RESIZE_BOTTOM, ///<  combination of right, top and bottom resize flag
 
 	/* The following flags are used by the system to specify what is disabled, hidden, or clicked
 	 * They are used in the same place as the above RESIZE_x flags, Widget visual_flags.
@@ -66,9 +66,8 @@ typedef enum ResizeFlags {
 	WIDG_LOWERED  = 6,  ///< widget is paint lowered, a pressed button in fact
 } ResizeFlag;
 
-/* used to indicate the end of widgets' list for vararg functions */
 enum {
-	WIDGET_LIST_END = -1,
+	WIDGET_LIST_END = -1, ///< indicate the end of widgets' list for vararg functions
 };
 
 typedef struct Widget {
@@ -237,7 +236,6 @@ typedef struct Scrollbar {
 typedef struct ResizeInfo {
 	uint width; ///< Minimum width and height
 	uint height;
-
 	uint step_width; ///< In how big steps the width and height go
 	uint step_height;
 } ResizeInfo;
@@ -431,7 +429,7 @@ typedef struct {
 assert_compile(WINDOW_CUSTOM_SIZE >= sizeof(scroller_d));
 
 typedef enum SortListFlags {
-	VL_NONE    = 0x00,
+	VL_NONE    = 0x00,  ///< no sort
 	VL_DESC    = 0x01,  ///< sort descending or ascending
 	VL_RESORT  = 0x02,  ///< instruct the code to resort the list in the next loop
 	VL_REBUILD = 0x04,  ///< create sort-listing to use for qsort and friends