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

 Some documentation addition, when i can easily supply them

19 files changed, 226 insertions, 194 deletions

diff --git a/src/date.cpp b/src/date.cpp
index 8210abc56..57149eff8 100644
--- a/src/date.cpp
+++ b/src/date.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file date.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "date.h"
@@ -197,11 +199,11 @@ extern void ShowEndGameChart(void);
 
 
 static const Month _autosave_months[] = {
-	 0, // never
-	 1, // every month
-	 3, // every 3 months
-	 6, // every 6 months
-	12, // every 12 months
+	 0, ///< never
+	 1, ///< every month
+	 3, ///< every 3 months
+	 6, ///< every 6 months
+	12, ///< every 12 months
 };
 
 /**
diff --git a/src/date.h b/src/date.h
index 488a9dc3a..c954d47d5 100644
--- a/src/date.h
+++ b/src/date.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file date.h */
+
 #ifndef DATE_H
 #define DATE_H
 
diff --git a/src/debug.cpp b/src/debug.cpp
index d21580665..2e416d515 100644
--- a/src/debug.cpp
+++ b/src/debug.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file debug.cpp */
+
 #include "stdafx.h"
 #include <stdio.h>
 #include <stdarg.h>
@@ -105,7 +107,7 @@ void SetDebugString(const char *s)
 	char *end;
 	const char *t;
 
-	// global debugging level?
+	/* global debugging level? */
 	if (*s >= '0' && *s <= '9') {
 		const DebugLevel *i;
 
@@ -115,19 +117,19 @@ void SetDebugString(const char *s)
 		for (i = debug_level; i != endof(debug_level); ++i) *i->level = v;
 	}
 
-	// individual levels
+	/* individual levels */
 	for (;;) {
 		const DebugLevel *i;
 		int *p;
 
-		// skip delimiters
+		/* skip delimiters */
 		while (*s == ' ' || *s == ',' || *s == '\t') s++;
 		if (*s == '\0') break;
 
 		t = s;
 		while (*s >= 'a' && *s <= 'z') s++;
 
-		// check debugging levels
+		/* check debugging levels */
 		p = NULL;
 		for (i = debug_level; i != endof(debug_level); ++i)
 			if (s == t + strlen(i->name) && strncmp(t, i->name, s - t) == 0) {
diff --git a/src/dedicated.cpp b/src/dedicated.cpp
index 1905fa498..d142edc0c 100644
--- a/src/dedicated.cpp
+++ b/src/dedicated.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dedicated.cpp */
+
 #include "stdafx.h"
 
 #ifdef ENABLE_NETWORK
@@ -43,7 +45,7 @@ void DedicatedFork(void)
 		}
 
 		default:
-			// We're the parent
+			/* We're the parent */
 			printf("Loading dedicated server...\n");
 			printf("  - Forked to background with pid %d\n", pid);
 			exit(0);
diff --git a/src/depot.cpp b/src/depot.cpp
index 889d2a35c..bb8843b15 100644
--- a/src/depot.cpp
+++ b/src/depot.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file depot.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "depot.h"
diff --git a/src/depot.h b/src/depot.h
index 7cf25a1b1..8e60f674e 100644
--- a/src/depot.h
+++ b/src/depot.h
@@ -1,11 +1,10 @@
 /* $Id$ */
 
+/** @file depot.h Header files for depots (not hangars) */
+
 #ifndef DEPOT_H
 #define DEPOT_H
 
-/** @file depot.h Header files for depots (not hangars)
- *  @see depot.c */
-
 #include "direction.h"
 #include "oldpool.h"
 #include "tile.h"
@@ -55,6 +54,7 @@ void ShowDepotWindow(TileIndex tile, byte type);
  * Get the new proposed service interval for the vehicle is indeed, clamped
  * within the given bounds. @see MIN_SERVINT_PERCENT ,etc.
  * @param index proposed service interval
+ * @return service interval
  */
 static inline Date GetServiceIntervalClamped(uint index)
 {
diff --git a/src/depot_gui.cpp b/src/depot_gui.cpp
index 66e7cde32..a033fe6cd 100644
--- a/src/depot_gui.cpp
+++ b/src/depot_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** depot_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -36,8 +38,8 @@ enum DepotWindowWidgets {
 	DEPOT_WIDGET_SELL_ALL,
 	DEPOT_WIDGET_AUTOREPLACE,
 	DEPOT_WIDGET_MATRIX,
-	DEPOT_WIDGET_V_SCROLL, // Vertical scrollbar
-	DEPOT_WIDGET_H_SCROLL, // Horizontal scrollbar
+	DEPOT_WIDGET_V_SCROLL, ///< Vertical scrollbar
+	DEPOT_WIDGET_H_SCROLL, ///< Horizontal scrollbar
 	DEPOT_WIDGET_BUILD,
 	DEPOT_WIDGET_CLONE,
 	DEPOT_WIDGET_LOCATION,
@@ -636,7 +638,7 @@ uint _block_sizes[4][2];
 /* Array to hold the default resize capacities
 * First part is the vehicle type, while the last is 0 = x, 1 = y */
 const uint _resize_cap[][2] = {
-/* VEH_Train */    {6, 10 * 29 + 36}, // flags, unitnumber and unit count uses a total of 36 pixels and we set default to 10 units
+/* VEH_Train */    {6, 10 * 29 + 36}, ///< flags, unitnumber and unit count uses a total of 36 pixels and we set default to 10 units
 /* VEH_Road */     {5, 5},
 /* VEH_Ship */     {3, 3},
 /* VEH_Aircraft */ {3, 4},
diff --git a/src/direction.h b/src/direction.h
index 576d8e1bb..5feda580c 100644
--- a/src/direction.h
+++ b/src/direction.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file direction.h */
+
 #ifndef DIRECTION_H
 #define DIRECTION_H
 
@@ -9,7 +11,7 @@
 typedef enum Direction {
 	DIR_BEGIN = 0,
 	DIR_N   = 0,
-	DIR_NE  = 1,      /* Northeast, upper right on your monitor */
+	DIR_NE  = 1,      ///< Northeast, upper right on your monitor
 	DIR_E   = 2,
 	DIR_SE  = 3,
 	DIR_S   = 4,
@@ -59,7 +61,7 @@ static inline Direction ChangeDir(Direction d, DirDiff delta)
 /* Direction commonly used as the direction of entering and leaving tiles, 4-way */
 typedef enum DiagDirection {
 	DIAGDIR_BEGIN = 0,
-	DIAGDIR_NE  = 0,      /* Northeast, upper right on your monitor */
+	DIAGDIR_NE  = 0,      ///< Northeast, upper right on your monitor
 	DIAGDIR_SE  = 1,
 	DIAGDIR_SW  = 2,
 	DIAGDIR_NW  = 3,
diff --git a/src/disaster_cmd.cpp b/src/disaster_cmd.cpp
index e4663e025..d9e6b8f17 100644
--- a/src/disaster_cmd.cpp
+++ b/src/disaster_cmd.cpp
@@ -99,13 +99,13 @@ static const SpriteID _disaster_images_8[] = {SPR_AH_64A, SPR_AH_64A, SPR_AH_64A
 static const SpriteID _disaster_images_9[] = {SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1, SPR_ROTOR_MOVING_1};
 
 static const SpriteID * const _disaster_images[] = {
-	_disaster_images_1, _disaster_images_1,                     // zeppeliner and zeppeliner shadow
-	_disaster_images_2, _disaster_images_2,                     // small ufo and small ufo shadow
-	_disaster_images_3, _disaster_images_3,                     // combat aircraft and shadow
-	_disaster_images_8, _disaster_images_8, _disaster_images_9, // combat helicopter, shadow and rotor
-	_disaster_images_6, _disaster_images_6,                     // big ufo and shadow
-	_disaster_images_7, _disaster_images_7,                     // skyranger and shadow
-	_disaster_images_4, _disaster_images_5,                     // small and big submarine sprites
+	_disaster_images_1, _disaster_images_1,                     ///< zeppeliner and zeppeliner shadow
+	_disaster_images_2, _disaster_images_2,                     ///< small ufo and small ufo shadow
+	_disaster_images_3, _disaster_images_3,                     ///< combat aircraft and shadow
+	_disaster_images_8, _disaster_images_8, _disaster_images_9, ///< combat helicopter, shadow and rotor
+	_disaster_images_6, _disaster_images_6,                     ///< big ufo and shadow
+	_disaster_images_7, _disaster_images_7,                     ///< skyranger and shadow
+	_disaster_images_4, _disaster_images_5,                     ///< small and big submarine sprites
 };
 
 static void DisasterVehicleUpdateImage(Vehicle *v)
@@ -1029,14 +1029,14 @@ static const struct {
 	Year min;
 	Year max;
 } _dis_years[] = {
-	{ 1930, 1955 }, // zeppeliner
-	{ 1940, 1970 }, // ufo (small)
-	{ 1960, 1990 }, // airplane
-	{ 1970, 2000 }, // helicopter
-	{ 2000, 2100 }, // ufo (big)
-	{ 1940, 1965 }, // submarine (small)
-	{ 1975, 2010 }, // submarine (big)
-	{ 1950, 1985 }  // coalmine
+	{ 1930, 1955 }, ///< zeppeliner
+	{ 1940, 1970 }, ///< ufo (small)
+	{ 1960, 1990 }, ///< airplane
+	{ 1970, 2000 }, ///< helicopter
+	{ 2000, 2100 }, ///< ufo (big)
+	{ 1940, 1965 }, ///< submarine (small)
+	{ 1975, 2010 }, ///< submarine (big)
+	{ 1950, 1985 }  ///< coalmine
 };
 
 
diff --git a/src/dock_gui.cpp b/src/dock_gui.cpp
index 8b3cda116..b0606a408 100644
--- a/src/dock_gui.cpp
+++ b/src/dock_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dock_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/sprites.h"
diff --git a/src/driver.cpp b/src/driver.cpp
index 6c25cfc8c..bc02df745 100644
--- a/src/driver.cpp
+++ b/src/driver.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file driver.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -143,13 +145,13 @@ void LoadDriver(int driver, const char *name)
 		char buffer[256];
 		const char* parms[32];
 
-		// Extract the driver name and put parameter list in parm
+		/* Extract the driver name and put parameter list in parm */
 		ttd_strlcpy(buffer, name, sizeof(buffer));
 		parm = strchr(buffer, ':');
 		parms[0] = NULL;
 		if (parm != NULL) {
 			uint np = 0;
-			// Tokenize the parm.
+			/* Tokenize the parm. */
 			do {
 				*parm++ = '\0';
 				if (np < lengthof(parms) - 1)
diff --git a/src/driver.h b/src/driver.h
index 4e25714f7..6a504362c 100644
--- a/src/driver.h
+++ b/src/driver.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file driver.h */
+
 #ifndef DRIVER_H
 #define DRIVER_H
 
diff --git a/src/dummy_land.cpp b/src/dummy_land.cpp
index 29b321d83..e01112bd0 100644
--- a/src/dummy_land.cpp
+++ b/src/dummy_land.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file dummy_land.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
diff --git a/src/economy.cpp b/src/economy.cpp
index 7575f6e9b..41bcc4237 100644
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file economy.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "currency.h"
@@ -35,7 +37,7 @@
 #include "date.h"
 #include "cargotype.h"
 
-// Score info
+/* Score info */
 const ScoreInfo _score_info[] = {
 	{ SCORE_VEHICLES,        120, 100 },
 	{ SCORE_STATIONS,         80, 100 },
@@ -90,8 +92,12 @@ int64 CalculateCompanyValue(const Player* p)
 	return max(value, 1LL);
 }
 
-// if update is set to true, the economy is updated with this score
-//  (also the house is updated, should only be true in the on-tick event)
+/** if update is set to true, the economy is updated with this score
+ *  (also the house is updated, should only be true in the on-tick event)
+ * @param update the economy with calculated score
+ * @param p player been evaluated
+ * @return actual score of this player
+ * */
 int UpdateCompanyRatingAndValue(Player *p, bool update)
 {
 	byte owner = p->index;
@@ -209,15 +215,15 @@ int UpdateCompanyRatingAndValue(Player *p, bool update)
 		_score_part[owner][SCORE_LOAN] = _score_info[SCORE_LOAN].needed - p->current_loan;
 	}
 
-	// Now we calculate the score for each item..
+	/* Now we calculate the score for each item.. */
 	{
 		int total_score = 0;
 		int s;
 		score = 0;
 		for (ScoreID i = SCORE_BEGIN; i < SCORE_END; i++) {
-			// Skip the total
+			/* Skip the total */
 			if (i == SCORE_TOTAL) continue;
-			// Check the score
+			/*  Check the score */
 			s = (_score_part[owner][i] >= _score_info[i].needed) ?
 				_score_info[i].score :
 				_score_part[owner][i] * _score_info[i].score / _score_info[i].needed;
@@ -228,7 +234,7 @@ int UpdateCompanyRatingAndValue(Player *p, bool update)
 
 		_score_part[owner][SCORE_TOTAL] = score;
 
-		// We always want the score scaled to SCORE_MAX (1000)
+		/*  We always want the score scaled to SCORE_MAX (1000) */
 		if (total_score != SCORE_MAX) score = score * SCORE_MAX / total_score;
 	}
 
@@ -242,7 +248,7 @@ int UpdateCompanyRatingAndValue(Player *p, bool update)
 	return score;
 }
 
-// use PLAYER_SPECTATOR as new_player to delete the player.
+/*  use PLAYER_SPECTATOR as new_player to delete the player. */
 void ChangeOwnershipOfPlayerItems(PlayerID old_player, PlayerID new_player)
 {
 	Town *t;
@@ -294,7 +300,7 @@ void ChangeOwnershipOfPlayerItems(PlayerID old_player, PlayerID new_player)
 		int num_aircraft = 0;
 		Vehicle *v;
 
-		// Determine Ids for the new vehicles
+		/*  Determine Ids for the new vehicles */
 		FOR_ALL_VEHICLES(v) {
 			if (v->owner == new_player) {
 				switch (v->type) {
@@ -328,7 +334,7 @@ void ChangeOwnershipOfPlayerItems(PlayerID old_player, PlayerID new_player)
 		}
 	}
 
-	// Change ownership of tiles
+	/*  Change ownership of tiles */
 	{
 		TileIndex tile = 0;
 		do {
@@ -368,7 +374,7 @@ static void PlayersCheckBankrupt(Player *p)
 	PlayerID owner;
 	int64 val;
 
-	// If the player has money again, it does not go bankrupt
+	/*  If the player has money again, it does not go bankrupt */
 	if (p->player_money >= 0) {
 		p->quarters_of_bankrupcy = 0;
 		return;
@@ -392,8 +398,8 @@ static void PlayersCheckBankrupt(Player *p)
 				break;
 			}
 
-			// Check if the company has any value.. if not, declare it bankrupt
-			//  right now
+			/* Check if the company has any value.. if not, declare it bankrupt
+			 *  right now */
 			val = CalculateCompanyValue(p);
 			if (val > 0) {
 				p->bankrupt_value = val;
@@ -401,13 +407,13 @@ static void PlayersCheckBankrupt(Player *p)
 				p->bankrupt_timeout = 0;
 				break;
 			}
-			// Else, falltrue to case 4...
+			/* Else, falltrue to case 4... */
 		}
 		case 4: {
-			// Close everything the owner has open
+			/* Close everything the owner has open */
 			DeletePlayerWindows(owner);
 
-//		Show bankrupt news
+			/* Show bankrupt news */
 			SetDParam(0, p->name_1);
 			SetDParam(1, p->name_2);
 			AddNewsItem( (StringID)(owner | NB_BBANKRUPT), NEWS_FLAGS(NM_CALLBACK, 0, NT_COMPANY_INFO, DNC_BANKRUPCY),0,0);
@@ -693,55 +699,55 @@ static byte _price_category[NUM_PRICES] = {
 };
 
 static const int32 _price_base[NUM_PRICES] = {
-	    100, // station_value
-	    100, // build_rail
-	     95, // build_road
-	     65, // build_signals
-	    275, // build_bridge
-	    600, // build_train_depot
-	    500, // build_road_depot
-	    700, // build_ship_depot
-	    450, // build_tunnel
-	    200, // train_station_track
-	    180, // train_station_length
-	    600, // build_airport
-	    200, // build_bus_station
-	    200, // build_truck_station
-	    350, // build_dock
-	 400000, // build_railvehicle
-	   2000, // build_railwagon
-	 700000, // aircraft_base
-	  14000, // roadveh_base
-	  65000, // ship_base
-	     20, // build_trees
-	    250, // terraform
-	     20, // clear_1
-	     40, // purchase_land
-	    200, // clear_2
-	    500, // clear_3
-	     20, // remove_trees
-	    -70, // remove_rail
-	     10, // remove_signals
-	     50, // clear_bridge
-	     80, // remove_train_depot
-	     80, // remove_road_depot
-	     90, // remove_ship_depot
-	     30, // clear_tunnel
-	  10000, // clear_water
-	     50, // remove_rail_station
-	     30, // remove_airport
-	     50, // remove_bus_station
-	     50, // remove_truck_station
-	     55, // remove_dock
-	   1600, // remove_house
-	     40, // remove_road
-	   5600, // running_rail[0] railroad
-	   5200, // running_rail[1] monorail
-	   4800, // running_rail[2] maglev
-	   9600, // aircraft_running
-	   1600, // roadveh_running
-	   5600, // ship_running
-	1000000, // build_industry
+	    100, ///< station_value
+	    100, ///< build_rail
+	     95, ///< build_road
+	     65, ///< build_signals
+	    275, ///< build_bridge
+	    600, ///< build_train_depot
+	    500, ///< build_road_depot
+	    700, ///< build_ship_depot
+	    450, ///< build_tunnel
+	    200, ///< train_station_track
+	    180, ///< train_station_length
+	    600, ///< build_airport
+	    200, ///< build_bus_station
+	    200, ///< build_truck_station
+	    350, ///< build_dock
+	 400000, ///< build_railvehicle
+	   2000, ///< build_railwagon
+	 700000, ///< aircraft_base
+	  14000, ///< roadveh_base
+	  65000, ///< ship_base
+	     20, ///< build_trees
+	    250, ///< terraform
+	     20, ///< clear_1
+	     40, ///< purchase_land
+	    200, ///< clear_2
+	    500, ///< clear_3
+	     20, ///< remove_trees
+	    -70, ///< remove_rail
+	     10, ///< remove_signals
+	     50, ///< clear_bridge
+	     80, ///< remove_train_depot
+	     80, ///< remove_road_depot
+	     90, ///< remove_ship_depot
+	     30, ///< clear_tunnel
+	  10000, ///< clear_water
+	     50, ///< remove_rail_station
+	     30, ///< remove_airport
+	     50, ///< remove_bus_station
+	     50, ///< remove_truck_station
+	     55, ///< remove_dock
+	   1600, ///< remove_house
+	     40, ///< remove_road
+	   5600, ///< running_rail[0] railroad
+	   5200, ///< running_rail[1] monorail
+	   4800, ///< running_rail[2] maglev
+	   9600, ///< aircraft_running
+	   1600, ///< roadveh_running
+	   5600, ///< ship_running
+	1000000, ///< build_industry
 };
 
 static byte price_base_multiplier[NUM_PRICES];
@@ -753,7 +759,7 @@ void ResetPriceBaseMultipliers(void)
 {
 	uint i;
 
-	// 8 means no multiplier.
+	/* 8 means no multiplier. */
 	for (i = 0; i < NUM_PRICES; i++)
 		price_base_multiplier[i] = 8;
 }
@@ -928,7 +934,7 @@ static void FindSubsidyCargoRoute(FoundRoute *fr)
 	fr->from = i = GetRandomIndustry();
 	if (i == NULL) return;
 
-	// Randomize cargo type
+	/* Randomize cargo type */
 	if (Random()&1 && i->produced_cargo[1] != CT_INVALID) {
 		cargo = i->produced_cargo[1];
 		trans = i->pct_transported[1];
@@ -939,28 +945,28 @@ static void FindSubsidyCargoRoute(FoundRoute *fr)
 		total = i->total_production[0];
 	}
 
-	// Quit if no production in this industry
-	//  or if the cargo type is passengers
-	//  or if the pct transported is already large enough
+	/* Quit if no production in this industry
+	 * or if the cargo type is passengers
+	 * or if the pct transported is already large enough */
 	if (total == 0 || trans > 42 || cargo == CT_INVALID || cargo == CT_PASSENGERS)
 		return;
 
 	fr->cargo = cargo;
 
 	if (cargo == CT_GOODS || cargo == CT_FOOD) {
-		// The destination is a town
+		/*  The destination is a town */
 		Town *t = GetRandomTown();
 
-		// Only want big towns
+		/* Only want big towns */
 		if (t == NULL || t->population < 900) return;
 
 		fr->distance = DistanceManhattan(i->xy, t->xy);
 		fr->to = t;
 	} else {
-		// The destination is an industry
+		/* The destination is an industry */
 		Industry *i2 = GetRandomIndustry();
 
-		// The industry must accept the cargo
+		/* The industry must accept the cargo */
 		if (i == i2 || i == NULL ||
 				(cargo != i2->accepts_cargo[0] &&
 				cargo != i2->accepts_cargo[1] &&
@@ -1018,9 +1024,9 @@ static void SubsidyMonthlyHandler(void)
 		}
 	}
 
-	// 25% chance to go on
+	/* 25% chance to go on */
 	if (CHANCE16(1,4)) {
-		// Find a free slot
+		/*  Find a free slot*/
 		s = _subsidies;
 		while (s->cargo_type != CT_INVALID) {
 			if (++s == endof(_subsidies))
@@ -1124,10 +1130,10 @@ static void DeliverGoodsToIndustry(TileIndex xy, CargoID cargo_type, int num_pie
 	Industry* ind;
 	uint u;
 
-	// Check if there's an industry close to the station that accepts the cargo
-	// XXX - Think of something better to
-	//       1) Only deliver to industries which are withing the catchment radius
-	//       2) Distribute between industries if more then one is present
+	/* Check if there's an industry close to the station that accepts the cargo
+	 * XXX - Think of something better to
+	 *       1) Only deliver to industries which are withing the catchment radius
+	 *       2) Distribute between industries if more then one is present */
 	u = (_patches.station_spread + 8) * 2;
 	FOR_ALL_INDUSTRIES(ind) {
 		uint t;
@@ -1158,7 +1164,7 @@ static bool CheckSubsidised(Station *from, Station *to, CargoID cargo_type)
 	Pair pair;
 	Player *p;
 
-	// check if there is an already existing subsidy that applies to us
+	/* check if there is an already existing subsidy that applies to us */
 	for (s = _subsidies; s != endof(_subsidies); s++) {
 		if (s->cargo_type == cargo_type &&
 				s->age >= 12 &&
@@ -1227,31 +1233,31 @@ static int32 DeliverGoods(int num_pieces, CargoID cargo_type, StationID source,
 
 	assert(num_pieces > 0);
 
-	// Update player statistics
+	/* Update player statistics */
 	{
 		Player *p = GetPlayer(_current_player);
 		p->cur_economy.delivered_cargo += num_pieces;
 		SETBIT(p->cargo_types, cargo_type);
 	}
 
-	// Get station pointers.
+	/* Get station pointers. */
 	s_from = GetStation(source);
 	s_to = GetStation(dest);
 
-	// Check if a subsidy applies.
+	/* Check if a subsidy applies. */
 	subsidised = CheckSubsidised(s_from, s_to, cargo_type);
 
-	// Increase town's counter for some special goods types
+	/* Increase town's counter for some special goods types */
 	if (cargo_type == CT_FOOD) s_to->town->new_act_food += num_pieces;
 	if (cargo_type == CT_WATER)  s_to->town->new_act_water += num_pieces;
 
-	// Give the goods to the industry.
+	/* Give the goods to the industry. */
 	DeliverGoodsToIndustry(s_to->xy, cargo_type, num_pieces);
 
-	// Determine profit
+	/* Determine profit */
 	profit = GetTransportedGoodsIncome(num_pieces, DistanceManhattan(source_tile, s_to->xy), days_in_transit, cargo_type);
 
-	// Modify profit if a subsidy is in effect
+	/* Modify profit if a subsidy is in effect */
 	if (subsidised) {
 		switch (_opt.diff.subsidy_multiplier) {
 			case 0:  profit += profit >> 1; break;
@@ -1377,10 +1383,10 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 			CLRBIT(u->load_status, LS_LOADING_FINISHED);
 
 			if (v->cargo_source != last_visited && ge->waiting_acceptance & 0x8000 && !(u->current_order.flags & OF_TRANSFER)) {
-				// deliver goods to the station
+				/* deliver goods to the station */
 				st->time_since_unload = 0;
 
-				unloading_time += v->cargo_count; /* TTDBUG: bug in original TTD */
+				unloading_time += v->cargo_count; // TTDBUG: bug in original TTD
 				if (just_arrived && v->cargo_paid_for < v->cargo_count) {
 					profit += DeliverGoods(v->cargo_count - v->cargo_paid_for, v->cargo_type, v->cargo_source, last_visited, v->cargo_source_xy, v->cargo_days);
 					v->cargo_paid_for = v->cargo_count;
@@ -1406,12 +1412,12 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 				unloading_time += v->cargo_count;
 				t = GB(ge->waiting_acceptance, 0, 12);
 				if (t == 0) {
-					// No goods waiting at station
+					/* No goods waiting at station */
 					ge->enroute_time = v->cargo_days;
 					ge->enroute_from = v->cargo_source;
 					ge->enroute_from_xy = v->cargo_source_xy;
 				} else {
-					// Goods already waiting at station. Set counters to the worst value.
+					/* Goods already waiting at station. Set counters to the worst value. */
 					if (v->cargo_days >= ge->enroute_time) ge->enroute_time = v->cargo_days;
 
 					if (last_visited != ge->enroute_from) {
@@ -1419,7 +1425,7 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 						ge->enroute_from_xy = v->cargo_source_xy;
 					}
 				}
-				// Update amount of waiting cargo
+				/* Update amount of waiting cargo */
 				SB(ge->waiting_acceptance, 0, 12, min(amount_unloaded + t, 0xFFF));
 
 				if (u->current_order.flags & OF_TRANSFER) {
@@ -1453,12 +1459,12 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 			default:        t = u->max_speed;               break;
 		}
 
-		// if last speed is 0, we treat that as if no vehicle has ever visited the station.
+		/* if last speed is 0, we treat that as if no vehicle has ever visited the station. */
 		ge->last_speed = min(t, 255);
 		ge->last_age = _cur_year - v->build_year;
 
-		// If there's goods waiting at the station, and the vehicle
-		//  has capacity for it, load it on the vehicle.
+		/* If there's goods waiting at the station, and the vehicle
+		 * has capacity for it, load it on the vehicle. */
 		if (count != 0 &&
 				(cap = v->cargo_cap - v->cargo_count) != 0) {
 			int cargoshare;
@@ -1475,7 +1481,7 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 			 * loading them. Since this will cause
 			 * VEHICLE_TRIGGER_EMPTY to be called at the time when
 			 * the whole vehicle chain is really totally empty, the
-			 * @completely_empty assignment can then be safely
+			 * completely_empty assignment can then be safely
 			 * removed; that's how TTDPatch behaves too. --pasky */
 			completely_empty = false;
 			anything_loaded = true;
@@ -1492,7 +1498,7 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 			unloading_time += cap;
 			st->time_since_load = 0;
 
-			// And record the source of the cargo, and the days in travel.
+			/* And record the source of the cargo, and the days in travel. */
 			v->cargo_source = ge->enroute_from;
 			v->cargo_source_xy = ge->enroute_from_xy;
 			v->cargo_days = ge->enroute_time;
@@ -1523,7 +1529,7 @@ int LoadUnloadVehicle(Vehicle *v, bool just_arrived)
 	}
 
 	if (v->type == VEH_Train) {
-		// Each platform tile is worth 2 rail vehicles.
+		/* Each platform tile is worth 2 rail vehicles. */
 		int overhang = v->u.rail.cached_total_length - st->GetPlatformLength(v->tile) * TILE_SIZE;
 		if (overhang > 0) {
 			unloading_time <<= 1;
@@ -1565,7 +1571,7 @@ void PlayersMonthlyLoop(void)
 	if (_patches.inflation && _cur_year < MAX_YEAR)
 		AddInflation();
 	PlayersPayInterest();
-	// Reset the _current_player flag
+	/* Reset the _current_player flag */
 	_current_player = OWNER_NONE;
 	HandleEconomyFluctuations();
 	SubsidyMonthlyHandler();
@@ -1582,7 +1588,7 @@ static void DoAcquireCompany(Player *p)
 	SetDParam(2, p->bankrupt_value);
 	AddNewsItem( (StringID)(_current_player | NB_BMERGER), NEWS_FLAGS(NM_CALLBACK, 0, NT_COMPANY_INFO, DNC_BANKRUPCY),0,0);
 
-	// original code does this a little bit differently
+	/* original code does this a little bit differently */
 	PlayerID pi = p->index;
 	ChangeOwnershipOfPlayerItems(pi, _current_player);
 
@@ -1679,7 +1685,7 @@ int32 CmdSellShareInCompany(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 	if (flags & DC_EXEC) {
 		PlayerByte* b = p->share_owners;
-		while (*b != _current_player) b++; /* share owners is guaranteed to contain player */
+		while (*b != _current_player) b++; // share owners is guaranteed to contain player
 		*b = PLAYER_SPECTATOR;
 		InvalidateWindow(WC_COMPANY, p1);
 	}
@@ -1712,14 +1718,14 @@ int32 CmdBuyCompany(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	return p->bankrupt_value;
 }
 
-// Prices
+/** Prices */
 static void SaveLoad_PRIC(void)
 {
 	SlArray(&_price,      NUM_PRICES, SLE_INT32);
 	SlArray(&_price_frac, NUM_PRICES, SLE_UINT16);
 }
 
-// Cargo payment rates
+/** Cargo payment rates */
 static void SaveLoad_CAPR(void)
 {
 	SlArray(&_cargo_payment_rates,      NUM_CARGO, SLE_INT32);
@@ -1736,7 +1742,7 @@ static const SaveLoad _economy_desc[] = {
 	SLE_END()
 };
 
-// Economy variables
+/** Economy variables */
 static void SaveLoad_ECMY(void)
 {
 	SlObject(&_economy, _economy_desc);
diff --git a/src/economy.h b/src/economy.h
index 7737eefd9..2e189a237 100644
--- a/src/economy.h
+++ b/src/economy.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file economy.h */
+
 #ifndef ECONOMY_H
 #define ECONOMY_H
 
@@ -7,15 +9,12 @@ void ResetPriceBaseMultipliers(void);
 void SetPriceBaseMultiplier(uint price, byte factor);
 
 typedef struct {
-	// Maximum possible loan
-	int32 max_loan;
-	int32 max_loan_unround;
-	// Economy fluctuation status
+	int32 max_loan;         ///< Maximum possible loan
+	int32 max_loan_unround; ///< Economy fluctuation status
 	int fluct;
-	// Interest
-	byte interest_rate;
-	byte infl_amount;
-	byte infl_amount_pr;
+	byte interest_rate;     ///< Interest
+	byte infl_amount;       ///< inflation amount
+	byte infl_amount_pr;    ///< "floating" portion of inflation
 } Economy;
 
 VARDEF Economy _economy;
@@ -40,19 +39,19 @@ enum ScoreID {
 	SCORE_CARGO      = 6,
 	SCORE_MONEY      = 7,
 	SCORE_LOAN       = 8,
-	SCORE_TOTAL      = 9, // This must always be the last entry
-	SCORE_END        = 10, // How many scores are there..
+	SCORE_TOTAL      = 9,  ///< This must always be the last entry
+	SCORE_END        = 10, ///< How many scores are there..
 
-	SCORE_MAX = 1000 // The max score that can be in the performance history
-	//  the scores together of score_info is allowed to be more!
+	SCORE_MAX = 1000       ///< The max score that can be in the performance history
+	/* the scores together of score_info is allowed to be more! */
 };
 
 DECLARE_POSTFIX_INCREMENT(ScoreID);
 
 typedef struct ScoreInfo {
-	byte id;    // Unique ID of the score
-	int needed; // How much you need to get the perfect score
-	int score;  // How much score it will give
+	byte id;    ///< Unique ID of the score
+	int needed; ///< How much you need to get the perfect score
+	int score;  ///< How much score it will give
 } ScoreInfo;
 
 extern const ScoreInfo _score_info[];
diff --git a/src/endian_check.cpp b/src/endian_check.cpp
index 97773496f..1cccb89eb 100644
--- a/src/endian_check.cpp
+++ b/src/endian_check.cpp
@@ -1,16 +1,17 @@
 /* $Id$ */
 
+/** @file endian_check.cpp
+ * This pretty simple file checks if the system is LITTLE_ENDIAN or BIG_ENDIAN
+ *  it does that by putting a 1 and a 0 in an array, and read it out as one
+ *  number. If it is 1, it is LITTLE_ENDIAN, if it is 256, it is BIG_ENDIAN
+ *
+ * After that it outputs the contents of an include files (endian.h)
+ *  that says or TTD_LITTLE_ENDIAN, or TTD_BIG_ENDIAN. Makefile takes
+ *  care of the real writing to the file. */
+
 #include <stdio.h>
 #include <string.h>
 
-// This pretty simple file checks if the system is LITTLE_ENDIAN or BIG_ENDIAN
-//  it does that by putting a 1 and a 0 in an array, and read it out as one
-//  number. If it is 1, it is LITTLE_ENDIAN, if it is 256, it is BIG_ENDIAN
-//
-// After that it outputs the contents of an include files (endian.h)
-//  that says or TTD_LITTLE_ENDIAN, or TTD_BIG_ENDIAN. Makefile takes
-//  care of the real writing to the file.
-
 int main (int argc, char *argv[]) {
 	unsigned char EndianTest[2] = { 1, 0 };
 	int force_BE = 0, force_LE = 0, force_PREPROCESSOR = 0;
@@ -31,9 +32,9 @@ int main (int argc, char *argv[]) {
 			printf("#define TTD_BIG_ENDIAN\n");
 		} else {
 			if (force_PREPROCESSOR == 1) {
-				// adding support for universal binaries on OSX
-				// Universal binaries supports both PPC and x86
-				// If a compiler for OSX gets this setting, it will always pick the correct endian and no test is needed
+				/** adding support for universal binaries on OSX
+				 * Universal binaries supports both PPC and x86
+				 * If a compiler for OSX gets this setting, it will always pick the correct endian and no test is needed */
 				printf("#ifdef __BIG_ENDIAN__\n");
 				printf("#define TTD_BIG_ENDIAN\n");
 				printf("#else\n");
diff --git a/src/engine.cpp b/src/engine.cpp
index af9794b72..54604c64e 100644
--- a/src/engine.cpp
+++ b/src/engine.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file engine.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -122,9 +124,9 @@ void StartupEngines(void)
 		e->flags = 0;
 		e->player_avail = 0;
 
-		// The magic value of 729 days below comes from the NewGRF spec. If the
-		// base intro date is before 1922 then the random number of days is not
-		// added.
+		/* The magic value of 729 days below comes from the NewGRF spec. If the
+		 * base intro date is before 1922 then the random number of days is not
+		 * added. */
 		r = Random();
 		e->intro_date = ei->base_intro <= ConvertYMDToDate(1922, 0, 1) ? ei->base_intro : (Date)GB(r, 0, 9) + ei->base_intro;
 		if (e->intro_date <= _date) {
@@ -154,7 +156,7 @@ void StartupEngines(void)
 
 		e->lifelength = ei->lifelength + _patches.extend_vehicle_life;
 
-		// prevent certain engines from ever appearing.
+		/* prevent certain engines from ever appearing. */
 		if (!HASBIT(ei->climates, _opt.landscape)) {
 			e->flags |= ENGINE_AVAILABLE;
 			e->player_avail = 0;
@@ -269,7 +271,7 @@ int32 CmdWantEnginePreview(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	return 0;
 }
 
-// Determine if an engine type is a wagon (and not a loco)
+/* Determine if an engine type is a wagon (and not a loco) */
 static bool IsWagon(EngineID index)
 {
 	return index < NUM_TRAIN_ENGINES && RailVehInfo(index)->railveh_type == RAILVEH_WAGON;
@@ -281,8 +283,8 @@ static void NewVehicleAvailable(Engine *e)
 	Player *p;
 	EngineID index = e - _engines;
 
-	// In case the player didn't build the vehicle during the intro period,
-	// prevent that player from getting future intro periods for a while.
+	/* In case the player didn't build the vehicle during the intro period,
+	 * prevent that player from getting future intro periods for a while. */
 	if (e->flags & ENGINE_INTRODUCING) {
 		FOR_ALL_PLAYERS(p) {
 			uint block_preview = p->block_preview;
@@ -308,14 +310,14 @@ static void NewVehicleAvailable(Engine *e)
 	e->flags = (e->flags & ~ENGINE_INTRODUCING) | ENGINE_AVAILABLE;
 	AddRemoveEngineFromAutoreplaceAndBuildWindows(e->type);
 
-	// Now available for all players
+	/* Now available for all players */
 	e->player_avail = (byte)-1;
 
-	// Do not introduce new rail wagons
+	/* Do not introduce new rail wagons */
 	if (IsWagon(index)) return;
 
 	if (index < NUM_TRAIN_ENGINES) {
-		// maybe make another rail type available
+		/* maybe make another rail type available */
 		RailType railtype = RailVehInfo(index)->railtype;
 		assert(railtype < RAILTYPE_END);
 		FOR_ALL_PLAYERS(p) {
@@ -338,20 +340,20 @@ void EnginesMonthlyLoop(void)
 
 	if (_cur_year < YEAR_ENGINE_AGING_STOPS) {
 		for (e = _engines; e != endof(_engines); e++) {
-			// Age the vehicle
+			/* Age the vehicle */
 			if (e->flags & ENGINE_AVAILABLE && e->age != 0xFFFF) {
 				e->age++;
 				CalcEngineReliability(e);
 			}
 
 			if (!(e->flags & ENGINE_AVAILABLE) && _date >= (e->intro_date + 365)) {
-				// Introduce it to all players
+				/* Introduce it to all players */
 				NewVehicleAvailable(e);
 			} else if (!(e->flags & (ENGINE_AVAILABLE|ENGINE_INTRODUCING)) && _date >= e->intro_date) {
-				// Introduction date has passed.. show introducing dialog to one player.
+				/* Introduction date has passed.. show introducing dialog to one player. */
 				e->flags |= ENGINE_INTRODUCING;
 
-				// Do not introduce new rail wagons
+				/* Do not introduce new rail wagons */
 				if (!IsWagon(e - _engines))
 					e->preview_player = (PlayerID)1; // Give to the player with the highest rating.
 			}
@@ -399,15 +401,15 @@ bool IsEngineBuildable(EngineID engine, byte type, PlayerID player)
 {
 	const Engine *e;
 
-	// check if it's an engine that is in the engine array
+	/* check if it's an engine that is in the engine array */
 	if (!IsEngineIndex(engine)) return false;
 
 	e = GetEngine(engine);
 
-	// check if it's an engine of specified type
+	/* check if it's an engine of specified type */
 	if (e->type != type) return false;
 
-	// check if it's available
+	/* check if it's available */
 	if (!HASBIT(e->player_avail, player)) return false;
 
 	return true;
@@ -595,7 +597,7 @@ static const SaveLoad _engine_desc[] = {
 	SLE_CONDNULL(1, 0, 44),
 	    SLE_VAR(Engine, player_avail,        SLE_UINT8),
 
-	// reserve extra space in savegame here. (currently 16 bytes)
+	/* reserve extra space in savegame here. (currently 16 bytes) */
 	SLE_CONDNULL(16, 2, SL_MAX_VERSION),
 
 	SLE_END()
diff --git a/src/engine.h b/src/engine.h
index 979dd46c3..fe77d2c52 100644
--- a/src/engine.h
+++ b/src/engine.h
@@ -1,19 +1,19 @@
 /* $Id$ */
 
+/** @file engine.h */
+
 #ifndef ENGINE_H
 #define ENGINE_H
 
-/** @file engine.h */
-
 #include "oldpool.h"
 #include "rail.h"
 #include "sound.h"
 #include "vehicle.h"
 
 enum RailVehicleTypes {
-	RAILVEH_SINGLEHEAD,
-	RAILVEH_MULTIHEAD,
-	RAILVEH_WAGON,
+	RAILVEH_SINGLEHEAD,  ///< indicates a "standalone" locomotive
+	RAILVEH_MULTIHEAD,   ///< indicates a combination of two locomotives
+	RAILVEH_WAGON,       ///< simple wagon, not motorized
 };
 
 typedef struct RailVehicleInfo {
@@ -26,7 +26,7 @@ typedef struct RailVehicleInfo {
 	uint16 weight;
 	byte running_cost_base;
 	byte running_cost_class;
-	byte engclass; // 0: steam, 1: diesel, 2: electric
+	byte engclass;         ///< 0: steam, 1: diesel, 2: electric
 	byte capacity;
 	CargoID cargo_type;
 	byte ai_rank;
@@ -36,9 +36,9 @@ typedef struct RailVehicleInfo {
 	                    //       for when the 'powered wagon' callback fails. But it should really also determine what
 	                    //       kind of visual effect to generate for a vehicle (default, steam, diesel, electric).
 	                    //       Same goes for the callback result, which atm is only used to check if a wagon is powered.
-	byte shorten_factor; // length on main map for this type is 8 - shorten_factor
+	byte shorten_factor;   ///< length on main map for this type is 8 - shorten_factor
 	byte tractive_effort; ///< Tractive effort coefficient
-	byte user_def_data; ///! Property 0x25: "User-defined bit mask" Used only for (very few) NewGRF vehicles
+	byte user_def_data;    ///< Property 0x25: "User-defined bit mask" Used only for (very few) NewGRF vehicles
 } RailVehicleInfo;
 
 typedef struct ShipVehicleInfo {
@@ -57,7 +57,7 @@ typedef struct ShipVehicleInfo {
  * in which case bit 1 tells us whether it's a big(fast) plane or not */
 enum {
 	AIR_HELI = 0,
-	AIR_CTOL = 1, // Conventional Take Off and Landing, i.e. planes
+	AIR_CTOL = 1, ///< Conventional Take Off and Landing, i.e. planes
 	AIR_FAST = 2
 };
 
@@ -111,7 +111,7 @@ typedef struct Engine {
 	PlayerByte preview_player;
 	byte preview_wait;
 	byte player_avail;
-	byte type; // type, ie VEH_Road, VEH_Train, etc. Same as in vehicle.h
+	byte type; ///< type, ie VEH_Road, VEH_Train, etc. Same as in vehicle.h
 } Engine;
 
 /**
diff --git a/src/engine_gui.cpp b/src/engine_gui.cpp
index ac80726bf..86157fa1a 100644
--- a/src/engine_gui.cpp
+++ b/src/engine_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file engine_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"