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

19 files changed, 388 insertions, 321 deletions

diff --git a/src/aircraft_cmd.cpp b/src/aircraft_cmd.cpp
index 7219298fd..31455665e 100644
--- a/src/aircraft_cmd.cpp
+++ b/src/aircraft_cmd.cpp
@@ -31,8 +31,8 @@
 #include "date.h"
 #include "spritecache.h"
 
-// this maps the terminal to its corresponding state and block flag
-// currently set for 10 terms, 4 helipads
+/** this maps the terminal to its corresponding state and block flag
+ *  currently set for 10 terms, 4 helipads */
 static const byte _airport_terminal_state[] = {2, 3, 4, 5, 6, 7, 19, 20, 0, 0, 8, 9, 21, 22};
 static const byte _airport_terminal_flag[] =  {0, 1, 2, 3, 4, 5, 22, 23, 0, 0, 6, 7, 24, 25};
 
@@ -56,7 +56,7 @@ static const SpriteID _aircraft_sprite[] = {
 	0x0EBD, 0x0EC5
 };
 
-/* Helicopter rotor animation states */
+/** Helicopter rotor animation states */
 enum HelicopterRotorStates {
 	HRS_ROTOR_STOPPED,
 	HRS_ROTOR_MOVING_1,
@@ -64,9 +64,11 @@ enum HelicopterRotorStates {
 	HRS_ROTOR_MOVING_3,
 };
 
-/* Find the nearest hangar to v
+/** Find the nearest hangar to v
  * INVALID_STATION is returned, if the player does not have any suitable
  * airports (like helipads only)
+ * @param v vehicle looking for a hangar
+ * @return the StationID if one is found, otherwise, INVALID_STATION
  */
 static StationID FindNearestHangar(const Vehicle *v)
 {
@@ -88,7 +90,7 @@ static StationID FindNearestHangar(const Vehicle *v)
 			continue;
 		}
 
-		// v->tile can't be used here, when aircraft is flying v->tile is set to 0
+		/* v->tile can't be used here, when aircraft is flying v->tile is set to 0 */
 		uint distance = DistanceSquare(vtile, st->airport_tile);
 		if (distance < best || index == INVALID_STATION) {
 			best = distance;
@@ -99,7 +101,9 @@ static StationID FindNearestHangar(const Vehicle *v)
 }
 
 #if 0
-// returns true if vehicle v have an airport in the schedule, that has a hangar
+/** Check if given vehicle has a goto hangar in his orders
+ * @param v vehicle to inquiry
+ * @return true if vehicle v has an airport in the schedule, that has a hangar */
 static bool HaveHangarInOrderList(Vehicle *v)
 {
 	const Order *order;
@@ -107,7 +111,7 @@ static bool HaveHangarInOrderList(Vehicle *v)
 	FOR_VEHICLE_ORDERS(v, order) {
 		const Station *st = GetStation(order->station);
 		if (st->owner == v->owner && st->facilities & FACIL_AIRPORT) {
-			// If an airport doesn't have a hangar, skip it
+			/* If an airport doesn't have a hangar, skip it */
 			if (st->Airport()->nof_depots != 0)
 				return true;
 		}
@@ -226,8 +230,10 @@ uint16 AircraftDefaultCargoCapacity(CargoID cid, const AircraftVehicleInfo *avi)
 
 /** Build an aircraft.
  * @param tile tile of depot where aircraft is built
+ * @param flags for command
  * @param p1 aircraft type being built (engine)
  * @param p2 bit 0 when set, the unitnumber will be 0, otherwise it will be a free number
+ * return result of operation.  Could be cost, error
  */
 int32 CmdBuildAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -236,14 +242,14 @@ int32 CmdBuildAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	const AircraftVehicleInfo *avi = AircraftVehInfo(p1);
 	int32 value = EstimateAircraftCost(avi);
 
-	// to just query the cost, it is not neccessary to have a valid tile (automation/AI)
+	/* to just query the cost, it is not neccessary to have a valid tile (automation/AI) */
 	if (flags & DC_QUERY_COST) return value;
 
 	if (!IsHangarTile(tile) || !IsTileOwner(tile, _current_player)) return CMD_ERROR;
 
 	SET_EXPENSES_TYPE(EXPENSES_NEW_VEHICLES);
 
-	// Prevent building aircraft types at places which can't handle them
+	/* Prevent building aircraft types at places which can't handle them */
 	const Station* st = GetStationByTile(tile);
 	const AirportFTAClass* apc = st->Airport();
 	if (!(apc->flags & (avi->subtype & AIR_CTOL ? AirportFTAClass::AIRPLANES : AirportFTAClass::HELICOPTERS))) {
@@ -387,7 +393,7 @@ int32 CmdBuildAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 		VehiclePositionChanged(v);
 		VehiclePositionChanged(u);
 
-		// Aircraft with 3 vehicles (chopper)?
+		/* Aircraft with 3 vehicles (chopper)? */
 		if (v->subtype == AIR_HELICOPTER) {
 			Vehicle *w = vl[2];
 
@@ -437,8 +443,10 @@ static void DoDeleteAircraft(Vehicle *v)
 
 /** Sell an aircraft.
  * @param tile unused
+ * @param flags for command type
  * @param p1 vehicle ID to be sold
  * @param p2 unused
+ * @return result of operation.  Error or sold value
  */
 int32 CmdSellAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -462,8 +470,10 @@ int32 CmdSellAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Start/Stop an aircraft.
  * @param tile unused
+ * @param flags for command type
  * @param p1 aircraft ID to start/stop
  * @param p2 unused
+ * @return result of operation.  Nothing if everything went well
  */
 int32 CmdStartStopAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -473,7 +483,7 @@ int32 CmdStartStopAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 	if (v->type != VEH_Aircraft || !CheckOwnership(v->owner)) return CMD_ERROR;
 
-	// cannot stop airplane when in flight, or when taking off / landing
+	/* cannot stop airplane when in flight, or when taking off / landing */
 	if (v->u.air.state >= STARTTAKEOFF && v->u.air.state < TERM7)
 		return_cmd_error(STR_A017_AIRCRAFT_IS_IN_FLIGHT);
 
@@ -501,10 +511,12 @@ int32 CmdStartStopAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Send an aircraft to the hangar.
  * @param tile unused
+ * @param flags for command type
  * @param p1 vehicle ID to send to the hangar
  * @param p2 various bitmasked elements
  * - p2 bit 0-3 - DEPOT_ flags (see vehicle.h)
  * - p2 bit 8-10 - VLW flag (for mass goto depot)
+ * @return o if everything went well
  */
 int32 CmdSendAircraftToHangar(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -545,7 +557,7 @@ int32 CmdSendAircraftToHangar(TileIndex tile, uint32 flags, uint32 p1, uint32 p2
 		const Station *st = GetStation(next_airport_index);
 		/* If the station is not a valid airport or if it has no hangars */
 		if (!st->IsValid() || st->airport_tile == 0 || st->Airport()->nof_depots == 0) {
-			// the aircraft has to search for a hangar on its own
+			/* the aircraft has to search for a hangar on its own */
 			StationID station = FindNearestHangar(v);
 
 			next_airport_has_hangar = false;
@@ -573,10 +585,12 @@ int32 CmdSendAircraftToHangar(TileIndex tile, uint32 flags, uint32 p1, uint32 p2
 
 /** Refits an aircraft to the specified cargo type.
  * @param tile unused
+ * @param flags for command type
  * @param p1 vehicle ID of the aircraft to refit
  * @param p2 various bitstuffed elements
  * - p2 = (bit 0-7) - the new cargo type to refit to
  * - p2 = (bit 8-15) - the new cargo subtype to refit to
+ * @return cost of refit or error
  */
 int32 CmdRefitAircraft(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -670,7 +684,7 @@ static void CheckIfAircraftNeedsService(Vehicle *v)
 	}
 
 	const Station *st = GetStation(v->current_order.dest);
-	// only goto depot if the target airport has terminals (eg. it is airport)
+	/* only goto depot if the target airport has terminals (eg. it is airport) */
 	if (st->IsValid() && st->airport_tile != 0 && st->Airport()->terminals != NULL) {
 //		printf("targetairport = %d, st->index = %d\n", v->u.air.targetairport, st->index);
 //		v->u.air.targetairport = st->index;
@@ -738,8 +752,8 @@ static void HelicopterTickHandler(Vehicle *v)
 
 	if (u->vehstatus & VS_HIDDEN) return;
 
-	// if true, helicopter rotors do not rotate. This should only be the case if a helicopter is
-	// loading/unloading at a terminal or stopped
+	/* if true, helicopter rotors do not rotate. This should only be the case if a helicopter is
+	 * loading/unloading at a terminal or stopped */
 	if (v->current_order.type == OT_LOADING || (v->vehstatus & VS_STOPPED)) {
 		if (u->cur_speed != 0) {
 			u->cur_speed++;
@@ -862,10 +876,10 @@ static bool UpdateAircraftSpeed(Vehicle *v, uint speed_limit)
 	if (speed_limit == SPEED_LIMIT_NONE) speed_limit = v->max_speed;
 	spd = min(v->cur_speed + (spd >> 8) + (v->subspeed < t), speed_limit);
 
-	// adjust speed for broken vehicles
+	/* adjust speed for broken vehicles */
 	if (v->vehstatus & VS_AIRCRAFT_BROKEN) spd = min(spd, SPEED_LIMIT_BROKEN);
 
-	//updates statusbar only if speed have changed to save CPU time
+	/* updates statusbar only if speed have changed to save CPU time */
 	if (spd != v->cur_speed) {
 		v->cur_speed = spd;
 		if (_patches.vehicle_speed)
@@ -921,21 +935,21 @@ static bool AircraftController(Vehicle *v)
 {
 	const Station *st = GetStation(v->u.air.targetairport);
 
-	// prevent going to 0,0 if airport is deleted.
+	/* prevent going to 0,0 if airport is deleted. */
 	TileIndex tile = st->airport_tile;
 	if (tile == 0) tile = st->xy;
 	int x = TileX(tile) * TILE_SIZE;
 	int y = TileY(tile) * TILE_SIZE;
 
-	// get airport moving data
+	/*  get airport moving data */
 	const AirportFTAClass *afc = st->Airport();
 	const AirportMovingData *amd = afc->MovingData(v->u.air.pos);
 
-	// Helicopter raise
+	/* Helicopter raise */
 	if (amd->flag & AMED_HELI_RAISE) {
 		Vehicle *u = v->next->next;
 
-		// Make sure the rotors don't rotate too fast
+		/* Make sure the rotors don't rotate too fast */
 		if (u->cur_speed > 32) {
 			v->cur_speed = 0;
 			if (--u->cur_speed == 32) SndPlayVehicleFx(SND_18_HELICOPTER, v);
@@ -944,7 +958,7 @@ static bool AircraftController(Vehicle *v)
 			if (UpdateAircraftSpeed(v, SPEED_LIMIT_NONE)) {
 				v->tile = 0;
 
-				// Reached altitude?
+				/* Reached altitude? */
 				if (v->z_pos >= 184) {
 					v->cur_speed = 0;
 					return true;
@@ -955,28 +969,28 @@ static bool AircraftController(Vehicle *v)
 		return false;
 	}
 
-	// Helicopter landing.
+	/* Helicopter landing. */
 	if (amd->flag & AMED_HELI_LOWER) {
 		if (UpdateAircraftSpeed(v, SPEED_LIMIT_NONE)) {
 			if (st->airport_tile == 0) {
-				// FIXME - AircraftController -> if station no longer exists, do not land
-				// helicopter will circle until sign disappears, then go to next order
-				// * what to do when it is the only order left, right now it just stays in 1 place
+				/* FIXME - AircraftController -> if station no longer exists, do not land
+				 * helicopter will circle until sign disappears, then go to next order
+				 * what to do when it is the only order left, right now it just stays in 1 place */
 				v->u.air.state = FLYING;
 				AircraftNextAirportPos_and_Order(v);
 				return false;
 			}
 
-			// Vehicle is now at the airport.
+			/* Vehicle is now at the airport. */
 			v->tile = st->airport_tile;
 
-			// Find altitude of landing position.
+			/* Find altitude of landing position. */
 			uint z = GetSlopeZ(x, y) + 1 + afc->delta_z;
 
 			if (z == v->z_pos) {
 				Vehicle *u = v->next->next;
 
-				// Increase speed of rotors. When speed is 80, we've landed.
+				/*  Increase speed of rotors. When speed is 80, we've landed. */
 				if (u->cur_speed >= 80) return true;
 				u->cur_speed += 4;
 			} else if (v->z_pos > z) {
@@ -988,19 +1002,19 @@ static bool AircraftController(Vehicle *v)
 		return false;
 	}
 
-	// Get distance from destination pos to current pos.
+	/* Get distance from destination pos to current pos. */
 	uint dist = myabs(x + amd->x - v->x_pos) +  myabs(y + amd->y - v->y_pos);
 
-	// Need exact position?
+	/* Need exact position? */
 	if (!(amd->flag & AMED_EXACTPOS) && dist <= (amd->flag & AMED_SLOWTURN ? 8U : 4U))
 		return true;
 
-	// At final pos?
+	/* At final pos? */
 	if (dist == 0) {
-		// Change direction smoothly to final direction.
+		/* Change direction smoothly to final direction. */
 		DirDiff dirdiff = DirDifference(amd->direction, v->direction);
-		// if distance is 0, and plane points in right direction, no point in calling
-		// UpdateAircraftSpeed(). So do it only afterwards
+		/* if distance is 0, and plane points in right direction, no point in calling
+		 * UpdateAircraftSpeed(). So do it only afterwards */
 		if (dirdiff == DIRDIFF_SAME) {
 			v->cur_speed = 0;
 			return true;
@@ -1019,7 +1033,7 @@ static bool AircraftController(Vehicle *v)
 
 	if (v->load_unload_time_rem != 0) v->load_unload_time_rem--;
 
-	// Turn. Do it slowly if in the air.
+	/* Turn. Do it slowly if in the air. */
 	Direction newdir = GetDirectionTowards(v, x + amd->x, y + amd->y);
 	if (newdir != v->direction) {
 		if (amd->flag & AMED_SLOWTURN) {
@@ -1031,15 +1045,15 @@ static bool AircraftController(Vehicle *v)
 		}
 	}
 
-	// Move vehicle.
+	/* Move vehicle. */
 	GetNewVehiclePosResult gp;
 	GetNewVehiclePos(v, &gp);
 	v->tile = gp.new_tile;
 
-	// If vehicle is in the air, use tile coordinate 0.
+	/* If vehicle is in the air, use tile coordinate 0. */
 	if (amd->flag & (AMED_TAKEOFF | AMED_SLOWTURN | AMED_LAND)) v->tile = 0;
 
-	// Adjust Z for land or takeoff?
+	/* Adjust Z for land or takeoff? */
 	uint z = v->z_pos;
 
 	if (amd->flag & AMED_TAKEOFF) {
@@ -1050,7 +1064,7 @@ static bool AircraftController(Vehicle *v)
 		if (st->airport_tile == 0) {
 			v->u.air.state = FLYING;
 			AircraftNextAirportPos_and_Order(v);
-			// get aircraft back on running altitude
+			/* get aircraft back on running altitude */
 			SetAircraftPosition(v, gp.x, gp.y, GetAircraftFlyingAltitude(v));
 			return false;
 		}
@@ -1067,7 +1081,7 @@ static bool AircraftController(Vehicle *v)
 		}
 	}
 
-	// We've landed. Decrase speed when we're reaching end of runway.
+	/* We've landed. Decrase speed when we're reaching end of runway. */
 	if (amd->flag & AMED_BRAKE) {
 		uint curz = GetSlopeZ(x, y) + 1;
 
@@ -1091,7 +1105,7 @@ static void HandleCrashedAircraft(Vehicle *v)
 
 	Station *st = GetStation(v->u.air.targetairport);
 
-	// make aircraft crash down to the ground
+	/* make aircraft crash down to the ground */
 	if (v->u.air.crashed_counter < 500 && st->airport_tile==0 && ((v->u.air.crashed_counter % 3) == 0) ) {
 		uint z = GetSlopeZ(v->x_pos, v->y_pos);
 		v->z_pos -= 1;
@@ -1118,14 +1132,14 @@ static void HandleCrashedAircraft(Vehicle *v)
 				EV_EXPLOSION_SMALL);
 		}
 	} else if (v->u.air.crashed_counter >= 10000) {
-		// remove rubble of crashed airplane
+		/*  remove rubble of crashed airplane */
 
-		// clear runway-in on all airports, set by crashing plane
-		// small airports use AIRPORT_BUSY, city airports use RUNWAY_IN_OUT_block, etc.
-		// but they all share the same number
+		/* clear runway-in on all airports, set by crashing plane
+		 * small airports use AIRPORT_BUSY, city airports use RUNWAY_IN_OUT_block, etc.
+		 * but they all share the same number */
 		CLRBITS(st->airport_flags, RUNWAY_IN_block);
 		CLRBITS(st->airport_flags, RUNWAY_IN_OUT_block); // commuter airport
-		CLRBITS(st->airport_flags, RUNWAY_IN2_block); // intercontinental
+		CLRBITS(st->airport_flags, RUNWAY_IN2_block);    // intercontinental
 
 		BeginVehicleMove(v);
 		EndVehicleMove(v);
@@ -1217,7 +1231,7 @@ static void ProcessAircraftOrder(Vehicle *v)
 
 	v->current_order = *order;
 
-	// orders are changed in flight, ensure going to the right station
+	/* orders are changed in flight, ensure going to the right station */
 	if (order->type == OT_GOTO_STATION && v->u.air.state == FLYING) {
 		AircraftNextAirportPos_and_Order(v);
 	}
@@ -1310,7 +1324,7 @@ static void MaybeCrashAirplane(Vehicle *v)
 {
 	Station *st = GetStation(v->u.air.targetairport);
 
-	//FIXME -- MaybeCrashAirplane -> increase crashing chances of very modern airplanes on smaller than AT_METROPOLITAN airports
+	/* FIXME -- MaybeCrashAirplane -> increase crashing chances of very modern airplanes on smaller than AT_METROPOLITAN airports */
 	uint16 prob = 0x10000 / 1500;
 	if (st->Airport()->flags & AirportFTAClass::SHORT_STRIP &&
 			AircraftVehInfo(v->engine_type)->subtype & AIR_FAST &&
@@ -1320,7 +1334,7 @@ static void MaybeCrashAirplane(Vehicle *v)
 
 	if (GB(Random(), 0, 16) > prob) return;
 
-	// Crash the airplane. Remove all goods stored at the station.
+	/* Crash the airplane. Remove all goods stored at the station. */
 	for (uint i = 0; i != NUM_CARGO; i++) {
 		st->goods[i].rating = 1;
 		SB(st->goods[i].waiting_acceptance, 0, 12, 0);
@@ -1329,7 +1343,7 @@ static void MaybeCrashAirplane(Vehicle *v)
 	CrashAirplane(v);
 }
 
-// we've landed and just arrived at a terminal
+/** we've landed and just arrived at a terminal */
 static void AircraftEntersTerminal(Vehicle *v)
 {
 	if (v->current_order.type == OT_GOTO_DEPOT) return;
@@ -1343,7 +1357,7 @@ static void AircraftEntersTerminal(Vehicle *v)
 
 		st->had_vehicle_of_type |= HVOT_AIRCRAFT;
 		SetDParam(0, st->index);
-		// show newsitem of celebrating citizens
+		/* show newsitem of celebrating citizens */
 		flags = (v->owner == _local_player) ? NEWS_FLAGS(NM_THIN, NF_VIEWPORT|NF_VEHICLE, NT_ARRIVAL_PLAYER, 0) : NEWS_FLAGS(NM_THIN, NF_VIEWPORT|NF_VEHICLE, NT_ARRIVAL_OTHER, 0);
 		AddNewsItem(
 			STR_A033_CITIZENS_CELEBRATE_FIRST,
@@ -1420,7 +1434,7 @@ static byte AircraftGetEntryPoint(const Vehicle *v, const AirportFTAClass *apc)
 }
 
 
-// set the right pos when heading to other airports after takeoff
+/** set the right pos when heading to other airports after takeoff */
 static void AircraftNextAirportPos_and_Order(Vehicle *v)
 {
 	if (v->current_order.type == OT_GOTO_STATION ||
@@ -1442,7 +1456,7 @@ static void AircraftLeaveHangar(Vehicle *v)
 		Vehicle *u = v->next;
 		u->vehstatus &= ~VS_HIDDEN;
 
-		// Rotor blades
+		/* Rotor blades */
 		u = u->next;
 		if (u != NULL) {
 			u->vehstatus &= ~VS_HIDDEN;
@@ -1472,16 +1486,16 @@ static void AircraftEventHandler_EnterHangar(Vehicle *v, const AirportFTAClass *
 	v->u.air.state = apc->layout[v->u.air.pos].heading;
 }
 
-// In an Airport Hangar
+/** In an Airport Hangar */
 static void AircraftEventHandler_InHangar(Vehicle *v, const AirportFTAClass *apc)
 {
-	// if we just arrived, execute EnterHangar first
+	/* if we just arrived, execute EnterHangar first */
 	if (v->u.air.previous_pos != v->u.air.pos) {
 		AircraftEventHandler_EnterHangar(v, apc);
 		return;
 	}
 
-	// if we were sent to the depot, stay there
+	/* if we were sent to the depot, stay there */
 	if (v->current_order.type == OT_GOTO_DEPOT && (v->vehstatus & VS_STOPPED)) {
 		v->current_order.type = OT_NOTHING;
 		v->current_order.flags = 0;
@@ -1492,37 +1506,37 @@ static void AircraftEventHandler_InHangar(Vehicle *v, const AirportFTAClass *apc
 			v->current_order.type != OT_GOTO_DEPOT)
 		return;
 
-	// if the block of the next position is busy, stay put
+	/* if the block of the next position is busy, stay put */
 	if (AirportHasBlock(v, &apc->layout[v->u.air.pos], apc)) return;
 
-	// We are already at the target airport, we need to find a terminal
+	/* We are already at the target airport, we need to find a terminal */
 	if (v->current_order.dest == v->u.air.targetairport) {
-		// FindFreeTerminal:
-		// 1. Find a free terminal, 2. Occupy it, 3. Set the vehicle's state to that terminal
+		/* FindFreeTerminal:
+		 * 1. Find a free terminal, 2. Occupy it, 3. Set the vehicle's state to that terminal */
 		if (v->subtype == AIR_HELICOPTER) {
 			if (!AirportFindFreeHelipad(v, apc)) return; // helicopter
 		} else {
 			if (!AirportFindFreeTerminal(v, apc)) return; // airplane
 		}
 	} else { // Else prepare for launch.
-		// airplane goto state takeoff, helicopter to helitakeoff
+		/* airplane goto state takeoff, helicopter to helitakeoff */
 		v->u.air.state = (v->subtype == AIR_HELICOPTER) ? HELITAKEOFF : TAKEOFF;
 	}
 	AircraftLeaveHangar(v);
 	AirportMove(v, apc);
 }
 
-// At one of the Airport's Terminals
+/** At one of the Airport's Terminals */
 static void AircraftEventHandler_AtTerminal(Vehicle *v, const AirportFTAClass *apc)
 {
-	// if we just arrived, execute EnterTerminal first
+	/* if we just arrived, execute EnterTerminal first */
 	if (v->u.air.previous_pos != v->u.air.pos) {
 		AircraftEventHandler_EnterTerminal(v, apc);
-		// on an airport with helipads, a helicopter will always land there
-		// and get serviced at the same time - patch setting
+		/* on an airport with helipads, a helicopter will always land there
+		 * and get serviced at the same time - patch setting */
 		if (_patches.serviceathelipad) {
 			if (v->subtype == AIR_HELICOPTER && apc->helipads != NULL) {
-				// an exerpt of ServiceAircraft, without the invisibility stuff
+				/* an exerpt of ServiceAircraft, without the invisibility stuff */
 				v->date_of_last_service = _date;
 				v->breakdowns_since_last_service = 0;
 				v->reliability = GetEngine(v->engine_type)->reliability;
@@ -1534,15 +1548,15 @@ static void AircraftEventHandler_AtTerminal(Vehicle *v, const AirportFTAClass *a
 
 	if (v->current_order.type == OT_NOTHING) return;
 
-	// if the block of the next position is busy, stay put
+	/* if the block of the next position is busy, stay put */
 	if (AirportHasBlock(v, &apc->layout[v->u.air.pos], apc)) return;
 
-	// airport-road is free. We either have to go to another airport, or to the hangar
-	// ---> start moving
+	/* airport-road is free. We either have to go to another airport, or to the hangar
+	 * ---> start moving */
 
 	switch (v->current_order.type) {
 		case OT_GOTO_STATION: // ready to fly to another airport
-			// airplane goto state takeoff, helicopter to helitakeoff
+			/* airplane goto state takeoff, helicopter to helitakeoff */
 			v->u.air.state = (v->subtype == AIR_HELICOPTER) ? HELITAKEOFF : TAKEOFF;
 			break;
 		case OT_GOTO_DEPOT:   // visit hangar for serivicing, sale, etc.
@@ -1580,7 +1594,7 @@ static void AircraftEventHandler_StartTakeOff(Vehicle *v, const AirportFTAClass
 static void AircraftEventHandler_EndTakeOff(Vehicle *v, const AirportFTAClass *apc)
 {
 	v->u.air.state = FLYING;
-	// get the next position to go to, differs per airport
+	/* get the next position to go to, differs per airport */
 	AircraftNextAirportPos_and_Order(v);
 }
 
@@ -1589,11 +1603,11 @@ static void AircraftEventHandler_HeliTakeOff(Vehicle *v, const AirportFTAClass *
 	const Player* p = GetPlayer(v->owner);
 	v->sprite_width = v->sprite_height = 24; // ??? no idea what this is
 	v->u.air.state = FLYING;
-	// get the next position to go to, differs per airport
+	/* get the next position to go to, differs per airport */
 	AircraftNextAirportPos_and_Order(v);
 
-	// check if the aircraft needs to be replaced or renewed and send it to a hangar if needed
-	// unless it is due for renewal but the engine is no longer available
+	/* check if the aircraft needs to be replaced or renewed and send it to a hangar if needed
+	 * unless it is due for renewal but the engine is no longer available */
 	if (v->owner == _local_player && (
 				EngineHasReplacementForPlayer(p, v->engine_type) ||
 				((p->engine_renew && v->age - v->max_age > p->engine_renew_months * 30) &&
@@ -1609,7 +1623,7 @@ static void AircraftEventHandler_Flying(Vehicle *v, const AirportFTAClass *apc)
 {
 	Station *st = GetStation(v->u.air.targetairport);
 
-	// runway busy or not allowed to use this airstation, circle
+	/* runway busy or not allowed to use this airstation, circle */
 	if (apc->flags & (v->subtype == AIR_HELICOPTER ? AirportFTAClass::HELICOPTERS : AirportFTAClass::AIRPLANES) &&
 			st->airport_tile != 0 &&
 			(st->owner == OWNER_NONE || st->owner == v->owner)) {
@@ -1620,16 +1634,16 @@ static void AircraftEventHandler_Flying(Vehicle *v, const AirportFTAClass *apc)
 		const AirportFTA *current = apc->layout[v->u.air.pos].next;
 		while (current != NULL) {
 			if (current->heading == landingtype) {
-				// save speed before, since if AirportHasBlock is false, it resets them to 0
-				// we don't want that for plane in air
-				// hack for speed thingie
+				/* save speed before, since if AirportHasBlock is false, it resets them to 0
+				 * we don't want that for plane in air
+				 * hack for speed thingie */
 				uint16 tcur_speed = v->cur_speed;
 				uint16 tsubspeed = v->subspeed;
 				if (!AirportHasBlock(v, current, apc)) {
 					v->u.air.state = landingtype; // LANDING / HELILANDING
-					// it's a bit dirty, but I need to set position to next position, otherwise
-					// if there are multiple runways, plane won't know which one it took (because
-					// they all have heading LANDING). And also occupy that block!
+					/* it's a bit dirty, but I need to set position to next position, otherwise
+					 * if there are multiple runways, plane won't know which one it took (because
+					 * they all have heading LANDING). And also occupy that block! */
 					v->u.air.pos = current->next_position;
 					SETBITS(st->airport_flags, apc->layout[v->u.air.pos].block);
 					return;
@@ -1648,13 +1662,13 @@ static void AircraftEventHandler_Landing(Vehicle *v, const AirportFTAClass *apc)
 {
 	AircraftLandAirplane(v);  // maybe crash airplane
 	v->u.air.state = ENDLANDING;
-	// check if the aircraft needs to be replaced or renewed and send it to a hangar if needed
+	/* check if the aircraft needs to be replaced or renewed and send it to a hangar if needed */
 	if (v->current_order.type != OT_GOTO_DEPOT && v->owner == _local_player) {
-		// only the vehicle owner needs to calculate the rest (locally)
+		/* only the vehicle owner needs to calculate the rest (locally) */
 		const Player* p = GetPlayer(v->owner);
 		if (EngineHasReplacementForPlayer(p, v->engine_type) ||
 			(p->engine_renew && v->age - v->max_age > (p->engine_renew_months * 30))) {
-			// send the aircraft to the hangar at next airport
+			/* send the aircraft to the hangar at next airport */
 			_current_player = _local_player;
 			DoCommandP(v->tile, v->index, DEPOT_SERVICE, NULL, CMD_SEND_AIRCRAFT_TO_HANGAR | CMD_SHOW_NO_ERROR);
 			_current_player = OWNER_NONE;
@@ -1670,13 +1684,13 @@ static void AircraftEventHandler_HeliLanding(Vehicle *v, const AirportFTAClass *
 
 static void AircraftEventHandler_EndLanding(Vehicle *v, const AirportFTAClass *apc)
 {
-	// next block busy, don't do a thing, just wait
+	/* next block busy, don't do a thing, just wait */
 	if (AirportHasBlock(v, &apc->layout[v->u.air.pos], apc)) return;
 
-	// if going to terminal (OT_GOTO_STATION) choose one
-	// 1. in case all terminals are busy AirportFindFreeTerminal() returns false or
-	// 2. not going for terminal (but depot, no order),
-	// --> get out of the way to the hangar.
+	/* if going to terminal (OT_GOTO_STATION) choose one
+	 * 1. in case all terminals are busy AirportFindFreeTerminal() returns false or
+	 * 2. not going for terminal (but depot, no order),
+	 * --> get out of the way to the hangar. */
 	if (v->current_order.type == OT_GOTO_STATION) {
 		if (AirportFindFreeTerminal(v, apc)) return;
 	}
@@ -1686,16 +1700,16 @@ static void AircraftEventHandler_EndLanding(Vehicle *v, const AirportFTAClass *a
 
 static void AircraftEventHandler_HeliEndLanding(Vehicle *v, const AirportFTAClass *apc)
 {
-	// next block busy, don't do a thing, just wait
+	/*  next block busy, don't do a thing, just wait */
 	if (AirportHasBlock(v, &apc->layout[v->u.air.pos], apc)) return;
 
-	// if going to helipad (OT_GOTO_STATION) choose one. If airport doesn't have helipads, choose terminal
-	// 1. in case all terminals/helipads are busy (AirportFindFreeHelipad() returns false) or
-	// 2. not going for terminal (but depot, no order),
-	// --> get out of the way to the hangar IF there are terminals on the airport.
-	// --> else TAKEOFF
-	// the reason behind this is that if an airport has a terminal, it also has a hangar. Airplanes
-	// must go to a hangar.
+	/* if going to helipad (OT_GOTO_STATION) choose one. If airport doesn't have helipads, choose terminal
+	 * 1. in case all terminals/helipads are busy (AirportFindFreeHelipad() returns false) or
+	 * 2. not going for terminal (but depot, no order),
+	 * --> get out of the way to the hangar IF there are terminals on the airport.
+	 * --> else TAKEOFF
+	 * the reason behind this is that if an airport has a terminal, it also has a hangar. Airplanes
+	 * must go to a hangar. */
 	if (v->current_order.type == OT_GOTO_STATION) {
 		if (AirportFindFreeHelipad(v, apc)) return;
 	}
@@ -1731,7 +1745,7 @@ static AircraftStateHandler * const _aircraft_state_handlers[] = {
 
 static void AirportClearBlock(const Vehicle *v, const AirportFTAClass *apc)
 {
-	// we have left the previous block, and entered the new one. Free the previous block
+	/* we have left the previous block, and entered the new one. Free the previous block */
 	if (apc->layout[v->u.air.previous_pos].block != apc->layout[v->u.air.pos].block) {
 		Station *st = GetStation(v->u.air.targetairport);
 
@@ -1741,7 +1755,7 @@ static void AirportClearBlock(const Vehicle *v, const AirportFTAClass *apc)
 
 static void AirportGoToNextPosition(Vehicle *v)
 {
-	// if aircraft is not in position, wait until it is
+	/* if aircraft is not in position, wait until it is */
 	if (!AircraftController(v)) return;
 
 	const AirportFTAClass *apc = GetStation(v->u.air.targetairport)->Airport();
@@ -1750,17 +1764,17 @@ static void AirportGoToNextPosition(Vehicle *v)
 	AirportMove(v, apc); // move aircraft to next position
 }
 
-// gets pos from vehicle and next orders
+/* gets pos from vehicle and next orders */
 static bool AirportMove(Vehicle *v, const AirportFTAClass *apc)
 {
-	// error handling
+	/* error handling */
 	if (v->u.air.pos >= apc->nofelements) {
 		DEBUG(misc, 0, "[Ap] position %d is not valid for current airport. Max position is %d", v->u.air.pos, apc->nofelements-1);
 		assert(v->u.air.pos < apc->nofelements);
 	}
 
 	const AirportFTA *current = &apc->layout[v->u.air.pos];
-	// we have arrived in an important state (eg terminal, hangar, etc.)
+	/* we have arrived in an important state (eg terminal, hangar, etc.) */
 	if (current->heading == v->u.air.state) {
 		byte prev_pos = v->u.air.pos; // location could be changed in state, so save it before-hand
 		_aircraft_state_handlers[v->u.air.state](v, apc);
@@ -1770,7 +1784,7 @@ static bool AirportMove(Vehicle *v, const AirportFTAClass *apc)
 
 	v->u.air.previous_pos = v->u.air.pos; // save previous location
 
-	// there is only one choice to move to
+	/* there is only one choice to move to */
 	if (current->next == NULL) {
 		if (AirportSetBlocks(v, current, apc)) {
 			v->u.air.pos = current->next_position;
@@ -1778,8 +1792,8 @@ static bool AirportMove(Vehicle *v, const AirportFTAClass *apc)
 		return false;
 	}
 
-	// there are more choices to choose from, choose the one that
-	// matches our heading
+	/* there are more choices to choose from, choose the one that
+	 * matches our heading */
 	do {
 		if (v->u.air.state == current->heading || current->heading == TO_ALL) {
 			if (AirportSetBlocks(v, current, apc)) {
@@ -1795,18 +1809,18 @@ static bool AirportMove(Vehicle *v, const AirportFTAClass *apc)
 	return false;
 }
 
-// returns true if the road ahead is busy, eg. you must wait before proceeding
+/*  returns true if the road ahead is busy, eg. you must wait before proceeding */
 static bool AirportHasBlock(Vehicle *v, const AirportFTA *current_pos, const AirportFTAClass *apc)
 {
 	const AirportFTA *reference = &apc->layout[v->u.air.pos];
 	const AirportFTA *next = &apc->layout[current_pos->next_position];
 
-	// same block, then of course we can move
+	/* same block, then of course we can move */
 	if (apc->layout[current_pos->position].block != next->block) {
 		const Station *st = GetStation(v->u.air.targetairport);
 		uint64 airport_flags = next->block;
 
-		// check additional possible extra blocks
+		/* check additional possible extra blocks */
 		if (current_pos != reference && current_pos->block != NOTHING_block) {
 			airport_flags |= current_pos->block;
 		}
@@ -1820,17 +1834,23 @@ static bool AirportHasBlock(Vehicle *v, const AirportFTA *current_pos, const Air
 	return false;
 }
 
-// returns true on success. Eg, next block was free and we have occupied it
+/**
+ * ...
+ * @param v airplane that requires the operation
+ * @param currentpos of the vehicle in the list of blocks
+ * @param apc airport on which block is requsted to be set
+ * @returns true on success. Eg, next block was free and we have occupied it
+ */
 static bool AirportSetBlocks(Vehicle *v, const AirportFTA *current_pos, const AirportFTAClass *apc)
 {
 	const AirportFTA *next = &apc->layout[current_pos->next_position];
 	const AirportFTA *reference = &apc->layout[v->u.air.pos];
 
-	// if the next position is in another block, check it and wait until it is free
+	/* if the next position is in another block, check it and wait until it is free */
 	if ((apc->layout[current_pos->position].block & next->block) != next->block) {
 		uint64 airport_flags = next->block;
-		//search for all all elements in the list with the same state, and blocks != N
-		// this means more blocks should be checked/set
+		/* search for all all elements in the list with the same state, and blocks != N
+		 * this means more blocks should be checked/set */
 		const AirportFTA *current = current_pos;
 		if (current == reference) current = current->next;
 		while (current != NULL) {
@@ -1841,8 +1861,8 @@ static bool AirportSetBlocks(Vehicle *v, const AirportFTA *current_pos, const Ai
 			current = current->next;
 		};
 
-		// if the block to be checked is in the next position, then exclude that from
-		// checking, because it has been set by the airplane before
+		/* if the block to be checked is in the next position, then exclude that from
+		 * checking, because it has been set by the airplane before */
 		if (current_pos->block == next->block) airport_flags ^= next->block;
 
 		Station* st = GetStation(v->u.air.targetairport);
@@ -1864,7 +1884,7 @@ static bool FreeTerminal(Vehicle *v, byte i, byte last_terminal)
 	Station *st = GetStation(v->u.air.targetairport);
 	for (; i < last_terminal; i++) {
 		if (!HASBIT(st->airport_flags, _airport_terminal_flag[i])) {
-			// TERMINAL# HELIPAD#
+			/* TERMINAL# HELIPAD# */
 			v->u.air.state = _airport_terminal_state[i]; // start moving to that terminal/helipad
 			SETBIT(st->airport_flags, _airport_terminal_flag[i]); // occupy terminal/helipad
 			return true;
@@ -1901,13 +1921,13 @@ static bool AirportFindFreeTerminal(Vehicle *v, const AirportFTAClass *apc)
 		while (temp != NULL) {
 			if (temp->heading == 255) {
 				if (!HASBITS(st->airport_flags, temp->block)) {
-					//read which group do we want to go to?
-					//(the first free group)
+					/* read which group do we want to go to?
+					 * (the first free group) */
 					uint target_group = temp->next_position + 1;
 
-					//at what terminal does the group start?
-					//that means, sum up all terminals of
-					//groups with lower number
+					/* at what terminal does the group start?
+					 * that means, sum up all terminals of
+					 * groups with lower number */
 					uint group_start = 0;
 					for (uint i = 1; i < target_group; i++) {
 						group_start += apc->terminals[i];
@@ -1925,7 +1945,7 @@ static bool AirportFindFreeTerminal(Vehicle *v, const AirportFTAClass *apc)
 		}
 	}
 
-	// if there is only 1 terminalgroup, all terminals are checked (starting from 0 to max)
+	/* if there is only 1 terminalgroup, all terminals are checked (starting from 0 to max) */
 	return FreeTerminal(v, 0, GetNumTerminals(apc));
 }
 
@@ -1941,10 +1961,10 @@ static uint GetNumHelipads(const AirportFTAClass *apc)
 
 static bool AirportFindFreeHelipad(Vehicle *v, const AirportFTAClass *apc)
 {
-	// if an airport doesn't have helipads, use terminals
+	/* if an airport doesn't have helipads, use terminals */
 	if (apc->helipads == NULL) return AirportFindFreeTerminal(v, apc);
 
-	// if there are more helicoptergroups, pick one, just as in AirportFindFreeTerminal()
+	/* if there are more helicoptergroups, pick one, just as in AirportFindFreeTerminal() */
 	if (apc->helipads[0] > 1) {
 		const Station* st = GetStation(v->u.air.targetairport);
 		const AirportFTA* temp = apc->layout[v->u.air.pos].next;
@@ -1953,13 +1973,13 @@ static bool AirportFindFreeHelipad(Vehicle *v, const AirportFTAClass *apc)
 			if (temp->heading == 255) {
 				if (!HASBITS(st->airport_flags, temp->block)) {
 
-					//read which group do we want to go to?
-					//(the first free group)
+					/* read which group do we want to go to?
+					 * (the first free group) */
 					uint target_group = temp->next_position + 1;
 
-					//at what terminal does the group start?
-					//that means, sum up all terminals of
-					//groups with lower number
+					/* at what terminal does the group start?
+					 * that means, sum up all terminals of
+					 * groups with lower number */
 					uint group_start = 0;
 					for (uint i = 1; i < target_group; i++) {
 						group_start += apc->helipads[i];
@@ -1976,8 +1996,8 @@ static bool AirportFindFreeHelipad(Vehicle *v, const AirportFTAClass *apc)
 			temp = temp->next;
 		}
 	} else {
-		// only 1 helicoptergroup, check all helipads
-		// The blocks for helipads start after the last terminal (MAX_TERMINALS)
+		/* only 1 helicoptergroup, check all helipads
+		 * The blocks for helipads start after the last terminal (MAX_TERMINALS) */
 		return FreeTerminal(v, MAX_TERMINALS, GetNumHelipads(apc) + MAX_TERMINALS);
 	}
 	return false; // it shouldn't get here anytime, but just to be sure
@@ -2028,10 +2048,10 @@ void Aircraft_Tick(Vehicle *v)
 }
 
 
-// need to be called to load aircraft from old version
+/** need to be called to load aircraft from old version */
 void UpdateOldAircraft(void)
 {
-	// set airport_flags to 0 for all airports just to be sure
+	/* set airport_flags to 0 for all airports just to be sure */
 	Station *st;
 	FOR_ALL_STATIONS(st) {
 		st->airport_flags = 0; // reset airport
@@ -2039,10 +2059,10 @@ void UpdateOldAircraft(void)
 
 	Vehicle *v_oldstyle;
 	FOR_ALL_VEHICLES(v_oldstyle) {
-	// airplane has another vehicle with subtype 4 (shadow), helicopter also has 3 (rotor)
-	// skip those
+	/* airplane has another vehicle with subtype 4 (shadow), helicopter also has 3 (rotor)
+	 * skip those */
 		if (v_oldstyle->type == VEH_Aircraft && IsNormalAircraft(v_oldstyle)) {
-			// airplane in terminal stopped doesn't hurt anyone, so goto next
+			/* airplane in terminal stopped doesn't hurt anyone, so goto next */
 			if (v_oldstyle->vehstatus & VS_STOPPED && v_oldstyle->u.air.state == 0) {
 				v_oldstyle->u.air.state = HANGAR;
 				continue;
@@ -2056,10 +2076,10 @@ void UpdateOldAircraft(void)
 			GetNewVehiclePos(v_oldstyle, &gp); // get the position of the plane (to be used for setting)
 			v_oldstyle->tile = 0; // aircraft in air is tile=0
 
-			// correct speed of helicopter-rotors
+			/* correct speed of helicopter-rotors */
 			if (v_oldstyle->subtype == AIR_HELICOPTER) v_oldstyle->next->next->cur_speed = 32;
 
-			// set new position x,y,z
+			/* set new position x,y,z */
 			SetAircraftPosition(v_oldstyle, gp.x, gp.y, GetAircraftFlyingAltitude(v_oldstyle));
 		}
 	}
@@ -2067,7 +2087,7 @@ void UpdateOldAircraft(void)
 
 void UpdateAirplanesOnNewStation(const Station *st)
 {
-	// only 1 station is updated per function call, so it is enough to get entry_point once
+	/* only 1 station is updated per function call, so it is enough to get entry_point once */
 	const AirportFTAClass *ap = st->Airport();
 
 	Vehicle *v;
@@ -2075,22 +2095,21 @@ void UpdateAirplanesOnNewStation(const Station *st)
 		if (v->type == VEH_Aircraft && IsNormalAircraft(v)) {
 			if (v->u.air.targetairport == st->index) { // if heading to this airport
 				/* update position of airplane. If plane is not flying, landing, or taking off
-				 *you cannot delete airport, so it doesn't matter
-				 */
+				 *you cannot delete airport, so it doesn't matter */
 				if (v->u.air.state >= FLYING) { // circle around
 					v->u.air.pos = v->u.air.previous_pos = AircraftGetEntryPoint(v, ap);
 					v->u.air.state = FLYING;
-					// landing plane needs to be reset to flying height (only if in pause mode upgrade,
-					// in normal mode, plane is reset in AircraftController. It doesn't hurt for FLYING
+					/* landing plane needs to be reset to flying height (only if in pause mode upgrade,
+					 * in normal mode, plane is reset in AircraftController. It doesn't hurt for FLYING */
 					GetNewVehiclePosResult gp;
 					GetNewVehiclePos(v, &gp);
-					// set new position x,y,z
+					/* set new position x,y,z */
 					SetAircraftPosition(v, gp.x, gp.y, GetAircraftFlyingAltitude(v));
 				} else {
 					assert(v->u.air.state == ENDTAKEOFF || v->u.air.state == HELITAKEOFF);
 					byte takeofftype = (v->subtype == AIR_HELICOPTER) ? HELITAKEOFF : ENDTAKEOFF;
-					// search in airportdata for that heading
-					// easiest to do, since this doesn't happen a lot
+					/* search in airportdata for that heading
+					 * easiest to do, since this doesn't happen a lot */
 					for (uint cnt = 0; cnt < ap->nofelements; cnt++) {
 						if (ap->layout[cnt].heading == takeofftype) {
 							v->u.air.pos = ap->layout[cnt].position;
diff --git a/src/bmp.cpp b/src/bmp.cpp
index 381d95014..4ee43c4cf 100644
--- a/src/bmp.cpp
+++ b/src/bmp.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file bmp.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "gfx.h"
diff --git a/src/bmp.h b/src/bmp.h
index 0587bab65..e67b611e6 100644
--- a/src/bmp.h
+++ b/src/bmp.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file bmp.h */
+
 #ifndef BMP_H
 #define BMP_H
 
diff --git a/src/bridge_map.cpp b/src/bridge_map.cpp
index 416e603c5..6dd8b48c6 100644
--- a/src/bridge_map.cpp
+++ b/src/bridge_map.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file bridge_map.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "bridge_map.h"
@@ -43,7 +45,7 @@ uint GetBridgeHeight(TileIndex t)
 	Slope tileh = GetTileSlope(t, &h);
 	uint f = GetBridgeFoundation(tileh, DiagDirToAxis(GetBridgeRampDirection(t)));
 
-	// one height level extra if the ramp is on a flat foundation
+	/* one height level extra if the ramp is on a flat foundation */
 	return
 		h + TILE_HEIGHT +
 		(IS_INT_INSIDE(f, 1, 15) ? TILE_HEIGHT : 0) +
diff --git a/src/bridge_map.h b/src/bridge_map.h
index 260917e19..b4ab3a68a 100644
--- a/src/bridge_map.h
+++ b/src/bridge_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file bridge_map.h */
+
 #ifndef BRIDGE_MAP_H
 #define BRIDGE_MAP_H
 
@@ -59,6 +61,8 @@ static inline uint GetBridgeType(TileIndex t)
 
 /**
  * Get the direction pointing onto the bridge
+ * @param tile The tile to analyze
+ * @return the above mentionned direction
  */
 static inline DiagDirection GetBridgeRampDirection(TileIndex t)
 {
diff --git a/src/build_vehicle_gui.cpp b/src/build_vehicle_gui.cpp
index e9b4ff6f0..9992b5a69 100644
--- a/src/build_vehicle_gui.cpp
+++ b/src/build_vehicle_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file build_vehicle_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "train.h"
@@ -607,9 +609,9 @@ static void GenerateBuildTrainList(Window *w)
 	EngList_RemoveAll(&bv->eng_list);
 
 	/* Make list of all available train engines and wagons.
-		* Also check to see if the previously selected engine is still available,
-		* and if not, reset selection to INVALID_ENGINE. This could be the case
-	* when engines become obsolete and are removed */
+	 * Also check to see if the previously selected engine is still available,
+	 * and if not, reset selection to INVALID_ENGINE. This could be the case
+	 * when engines become obsolete and are removed */
 	for (sel_id = INVALID_ENGINE, eid = 0; eid < NUM_TRAIN_ENGINES; eid++) {
 		const RailVehicleInfo *rvi = RailVehInfo(eid);
 
@@ -628,15 +630,15 @@ static void GenerateBuildTrainList(Window *w)
 
 	bv->sel_engine = sel_id;
 
-	// make engines first, and then wagons, sorted by ListPositionOfEngine()
+	/* make engines first, and then wagons, sorted by ListPositionOfEngine() */
 	_internal_sort_order = false;
 	EngList_Sort(&bv->eng_list, TrainEnginesThenWagonsSorter);
 
-	// and then sort engines
+	/* and then sort engines */
 	_internal_sort_order = bv->descending_sort_order;
 	EngList_SortPartial(&bv->eng_list, _sorter[0][bv->sort_criteria], 0, num_engines);
 
-	// and finally sort wagons
+	/* and finally sort wagons */
 	EngList_SortPartial(&bv->eng_list, _sorter[0][bv->sort_criteria], num_engines, num_wagons);
 }
 
@@ -694,7 +696,7 @@ static void GenerateBuildAircraftList(Window *w)
 	for (eid = AIRCRAFT_ENGINES_INDEX; eid < AIRCRAFT_ENGINES_INDEX + NUM_AIRCRAFT_ENGINES; eid++) {
 		if (IsEngineBuildable(eid, VEH_Aircraft, _local_player)) {
 			const AircraftVehicleInfo *avi = AircraftVehInfo(eid);
-			switch (bv->filter.flags & ~AirportFTAClass::SHORT_STRIP /* we don't care about the length of the runway here */) {
+			switch (bv->filter.flags & ~AirportFTAClass::SHORT_STRIP) { // we don't care about the length of the runway here
 				case AirportFTAClass::HELICOPTERS:
 					if (avi->subtype != AIR_HELI) continue;
 					break;
@@ -934,7 +936,7 @@ static void NewVehicleWndProc(Window *w, WindowEvent *e)
 			break;
 		}
 
-		case WE_DROPDOWN_SELECT: /* we have selected a dropdown item in the list */
+		case WE_DROPDOWN_SELECT: // we have selected a dropdown item in the list
 			if (bv->sort_criteria != e->we.dropdown.index) {
 				bv->sort_criteria = e->we.dropdown.index;
 				_last_sort_criteria[bv->vehicle_type] = bv->sort_criteria;
diff --git a/src/callback_table.cpp b/src/callback_table.cpp
index 65e140742..30dca7cac 100644
--- a/src/callback_table.cpp
+++ b/src/callback_table.cpp
@@ -1,57 +1,59 @@
 /* $Id$ */
 
+/** @file callback_table.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "callback_table.h"
 #include "functions.h"
 
-// If you add a callback for DoCommandP, also add the callback in here
-//   see below for the full list!
-// If you don't do it, it won't work across the network!!
+/* If you add a callback for DoCommandP, also add the callback in here
+ *   see below for the full list!
+ * If you don't do it, it won't work across the network!! */
 
-/* aircraft_gui.c */
+/* aircraft_gui.cpp */
 CommandCallback CcBuildAircraft;
 CommandCallback CcCloneAircraft;
 
-/* airport_gui.c */
+/* airport_gui.cpp */
 CommandCallback CcBuildAirport;
 
-/* bridge_gui.c */
+/* bridge_gui.cpp */
 CommandCallback CcBuildBridge;
 
-/* dock_gui.c */
+/* dock_gui.cpp */
 CommandCallback CcBuildDocks;
 CommandCallback CcBuildCanal;
 
-/* depot_gui.c */
+/* depot_gui.cpp */
 CommandCallback CcCloneVehicle;
 
-/* main_gui.c */
+/* main_gui.cpp */
 CommandCallback CcPlaySound10;
 CommandCallback CcPlaceSign;
 CommandCallback CcTerraform;
 CommandCallback CcBuildTown;
 
-/* rail_gui.c */
+/* rail_gui.cpp */
 CommandCallback CcPlaySound1E;
 CommandCallback CcRailDepot;
 CommandCallback CcStation;
 CommandCallback CcBuildRailTunnel;
 
-/* road_gui.c */
+/* road_gui.cpp */
 CommandCallback CcPlaySound1D;
 CommandCallback CcBuildRoadTunnel;
 CommandCallback CcRoadDepot;
 
-/* roadveh_gui.c */
+/* roadveh_gui.cpp */
 CommandCallback CcBuildRoadVeh;
 CommandCallback CcCloneRoadVeh;
 
-/* ship_gui.c */
+/* ship_gui.cpp */
 CommandCallback CcBuildShip;
 CommandCallback CcCloneShip;
 
-/* train_gui.c */
+/* train_gui.cpp */
 CommandCallback CcBuildWagon;
 CommandCallback CcBuildLoco;
 CommandCallback CcCloneTrain;
diff --git a/src/callback_table.h b/src/callback_table.h
index f555fcf60..142ff6915 100644
--- a/src/callback_table.h
+++ b/src/callback_table.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file callback_table.h  */
+
 #ifndef CALLBACK_TABLE_H
 #define CALLBACK_TABLE_H
 
diff --git a/src/cargotype.cpp b/src/cargotype.cpp
index 28fbce38b..5593b82bf 100644
--- a/src/cargotype.cpp
+++ b/src/cargotype.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cargotype.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "macros.h"
diff --git a/src/cargotype.h b/src/cargotype.h
index 684e463ab..0e4379517 100644
--- a/src/cargotype.h
+++ b/src/cargotype.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file cargotype.h */
+
 #ifndef CARGOTYPE_H
 #define CARGOTYPE_H
 
diff --git a/src/clear_cmd.cpp b/src/clear_cmd.cpp
index 32612dc81..44e735add 100644
--- a/src/clear_cmd.cpp
+++ b/src/clear_cmd.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file clear_cmd.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "clear_map.h"
@@ -107,9 +109,9 @@ static int TerraformProc(TerraformerState *ts, TileIndex tile, int mode)
 		Slope tileh;
 		uint z;
 
-		// Nothing could be built at the steep slope - this avoids a bug
-		// when you have a single diagonal track in one corner on a
-		// basement and then you raise/lower the other corner.
+		/* Nothing could be built at the steep slope - this avoids a bug
+		 * when you have a single diagonal track in one corner on a
+		 * basement and then you raise/lower the other corner. */
 		tileh = GetTileSlope(tile, &z);
 		if (tileh == unsafe_slope[mode] ||
 				tileh == ComplementSlope(unsafe_slope[mode])) {
@@ -118,8 +120,8 @@ static int TerraformProc(TerraformerState *ts, TileIndex tile, int mode)
 			return -1;
 		}
 
-		// If we have a single diagonal track there, the other side of
-		// tile can be terraformed.
+		/* If we have a single diagonal track there, the other side of
+		 * tile can be terraformed. */
 		if (IsPlainRailTile(tile) && GetTrackBits(tile) == safe_track[mode]) {
 			/* If terraforming downwards prevent damaging a potential tunnel below.
 			 * This check is only necessary for flat tiles, because if the tile is
@@ -223,8 +225,10 @@ static bool TerraformTileHeight(TerraformerState *ts, TileIndex tile, int height
 
 /** Terraform land
  * @param tile tile to terraform
+ * @param flags for this command type
  * @param p1 corners to terraform.
  * @param p2 direction; eg up or down
+ * @return error or cost of terraforming
  */
 int32 CmdTerraformLand(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -346,8 +350,10 @@ int32 CmdTerraformLand(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Levels a selected (rectangle) area of land
  * @param tile end tile of area-drag
+ * @param flags for this command type
  * @param p1 start tile of area drag
  * @param p2 unused
+ * @return  error or cost of terraforming
  */
 int32 CmdLevelLand(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -362,10 +368,10 @@ int32 CmdLevelLand(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 	SET_EXPENSES_TYPE(EXPENSES_CONSTRUCTION);
 
-	// remember level height
+	/* remember level height */
 	h = TileHeight(p1);
 
-	// make sure sx,sy are smaller than ex,ey
+	/* make sure sx,sy are smaller than ex,ey */
 	ex = TileX(tile);
 	ey = TileY(tile);
 	sx = TileX(p1);
@@ -405,8 +411,10 @@ int32 CmdLevelLand(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 /** Purchase a land area. Actually you only purchase one tile, so
  * the name is a bit confusing ;p
  * @param tile the tile the player is purchasing
+ * @param flags for this command type
  * @param p1 unused
  * @param p2 unused
+ * @return error of cost of operation
  */
 int32 CmdPurchaseLandArea(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -459,8 +467,10 @@ static int32 ClearTile_Clear(TileIndex tile, byte flags)
 /** Sell a land area. Actually you only sell one tile, so
  * the name is a bit confusing ;p
  * @param tile the tile the player is selling
+ * @param flags for this command type
  * @param p1 unused
  * @param p2 unused
+ * @return error or cost of operation
  */
 int32 CmdSellLandArea(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -787,17 +797,17 @@ void InitializeClearLand(void)
 }
 
 extern const TileTypeProcs _tile_type_clear_procs = {
-	DrawTile_Clear,           /* draw_tile_proc */
-	GetSlopeZ_Clear,          /* get_slope_z_proc */
-	ClearTile_Clear,          /* clear_tile_proc */
-	GetAcceptedCargo_Clear,   /* get_accepted_cargo_proc */
-	GetTileDesc_Clear,        /* get_tile_desc_proc */
-	GetTileTrackStatus_Clear, /* get_tile_track_status_proc */
-	ClickTile_Clear,          /* click_tile_proc */
-	AnimateTile_Clear,        /* animate_tile_proc */
-	TileLoop_Clear,           /* tile_loop_clear */
-	ChangeTileOwner_Clear,    /* change_tile_owner_clear */
-	NULL,                     /* get_produced_cargo_proc */
-	NULL,                     /* vehicle_enter_tile_proc */
-	GetSlopeTileh_Clear,      /* get_slope_tileh_proc */
+	DrawTile_Clear,           ///< draw_tile_proc
+	GetSlopeZ_Clear,          ///< get_slope_z_proc
+	ClearTile_Clear,          ///< clear_tile_proc
+	GetAcceptedCargo_Clear,   ///< get_accepted_cargo_proc
+	GetTileDesc_Clear,        ///< get_tile_desc_proc
+	GetTileTrackStatus_Clear, ///< get_tile_track_status_proc
+	ClickTile_Clear,          ///< click_tile_proc
+	AnimateTile_Clear,        ///< animate_tile_proc
+	TileLoop_Clear,           ///< tile_loop_clear
+	ChangeTileOwner_Clear,    ///< change_tile_owner_clear
+	NULL,                     ///< get_produced_cargo_proc
+	NULL,                     ///< vehicle_enter_tile_proc
+	GetSlopeTileh_Clear,      ///< get_slope_tileh_proc
 };
diff --git a/src/clear_map.h b/src/clear_map.h
index 88c3f4af0..b44d7ec99 100644
--- a/src/clear_map.h
+++ b/src/clear_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file clear_map.h */
+
 #ifndef CLEAR_MAP_H
 #define CLEAR_MAP_H
 
@@ -11,12 +13,12 @@
  * valid densities (bits 0...1) in comments after the enum
  */
 typedef enum ClearGround {
-	CLEAR_GRASS  = 0, // 0-3
-	CLEAR_ROUGH  = 1, // 3
-	CLEAR_ROCKS  = 2, // 3
-	CLEAR_FIELDS = 3, // 3
-	CLEAR_SNOW   = 4, // 0-3
-	CLEAR_DESERT = 5  // 1,3
+	CLEAR_GRASS  = 0, ///< 0-3
+	CLEAR_ROUGH  = 1, ///< 3
+	CLEAR_ROCKS  = 2, ///< 3
+	CLEAR_FIELDS = 3, ///< 3
+	CLEAR_SNOW   = 4, ///< 0-3
+	CLEAR_DESERT = 5  ///< 1,3
 } ClearGround;
 
 
@@ -134,7 +136,7 @@ static inline void MakeClear(TileIndex t, ClearGround g, uint density)
 	_m[t].m3 = 0;
 	_m[t].m4 = 0 << 5 | 0 << 2;
 	SetClearGroundDensity(t, g, density);
-	SB(_m[t].m6, 2, 4, 0); ///< Clear the rest of m6, bits 2 to 5
+	SB(_m[t].m6, 2, 4, 0); // Clear the rest of m6, bits 2 to 5
 }
 
 
diff --git a/src/command.cpp b/src/command.cpp
index bb2955dbb..8eebce553 100644
--- a/src/command.cpp
+++ b/src/command.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file command.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
@@ -347,7 +349,7 @@ int32 DoCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 flags, uint procc)
 
 	_docommand_recursive++;
 
-	// only execute the test call if it's toplevel, or we're not execing.
+	/* only execute the test call if it's toplevel, or we're not execing. */
 	if (_docommand_recursive == 1 || !(flags & DC_EXEC) || (flags & DC_FORCETEST) ) {
 		res = proc(tile, flags & ~DC_EXEC, p1, p2);
 		if (CmdFailed(res)) {
@@ -380,10 +382,10 @@ error:
 		return CMD_ERROR;
 	}
 
-	// if toplevel, subtract the money.
+	/* if toplevel, subtract the money. */
 	if (--_docommand_recursive == 0) {
 		SubtractMoneyFromPlayer(res);
-		// XXX - Old AI hack which doesn't use DoCommandDP; update last build coord of player
+		/* XXX - Old AI hack which doesn't use DoCommandDP; update last build coord of player */
 		if (tile != 0 && IsValidPlayer(_current_player)) {
 			GetPlayer(_current_player)->last_build_coordinate = tile;
 		}
@@ -400,8 +402,8 @@ int32 GetAvailableMoneyForCommand(void)
 	return GetPlayer(pid)->player_money;
 }
 
-// toplevel network safe docommand function for the current player. must not be called recursively.
-// the callback is called when the command succeeded or failed.
+/* toplevel network safe docommand function for the current player. must not be called recursively.
+ * the callback is called when the command succeeded or failed. */
 bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback, uint32 cmd)
 {
 	int32 res = 0,res2;
@@ -437,7 +439,7 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 	if (cmd & CMD_AUTO) flags |= DC_AUTO;
 	if (cmd & CMD_NO_WATER) flags |= DC_NO_WATER;
 
-	// get pointer to command handler
+	/* get pointer to command handler */
 	assert((cmd & 0xFF) < lengthof(_command_proc_table));
 	proc = _command_proc_table[cmd & 0xFF].proc;
 	if (proc == NULL) {
@@ -445,15 +447,15 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 		return false;
 	}
 
-	// Some commands have a different output in dryrun than the realrun
-	//  e.g.: if you demolish a whole town, the dryrun would say okay.
-	//  but by really destroying, your rating drops and at a certain point
-	//  it will fail. so res and res2 are different
-	// CMD_REMOVE_ROAD: This command has special local authority
-	// restrictions which may cause the test run to fail (the previous
-	// road fragments still stay there and the town won't let you
-	// disconnect the road system), but the exec will succeed and this
-	// fact will trigger an assertion failure. --pasky
+	/* Some commands have a different output in dryrun than the realrun
+	 *  e.g.: if you demolish a whole town, the dryrun would say okay.
+	 *  but by really destroying, your rating drops and at a certain point
+	 *  it will fail. so res and res2 are different
+	 * CMD_REMOVE_ROAD: This command has special local authority
+	 * restrictions which may cause the test run to fail (the previous
+	 * road fragments still stay there and the town won't let you
+	 * disconnect the road system), but the exec will succeed and this
+	 * fact will trigger an assertion failure. --pasky */
 	notest =
 		(cmd & 0xFF) == CMD_CLEAR_AREA ||
 		(cmd & 0xFF) == CMD_CONVERT_RAIL ||
@@ -463,13 +465,13 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 
 	_docommand_recursive = 1;
 
-	// cost estimation only?
+	/* cost estimation only? */
 	if (!IsGeneratingWorld() &&
 			_shift_pressed &&
 			IsLocalPlayer() &&
 			!(cmd & (CMD_NETWORK_COMMAND | CMD_SHOW_NO_ERROR)) &&
 			(cmd & 0xFF) != CMD_PAUSE) {
-		// estimate the cost.
+		/* estimate the cost. */
 		res = proc(tile, flags, p1, p2);
 		if (CmdFailed(res)) {
 			if (res & 0xFFFF) _error_message = res & 0xFFFF;
@@ -485,13 +487,13 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 
 
 	if (!((cmd & CMD_NO_TEST_IF_IN_NETWORK) && _networking)) {
-		// first test if the command can be executed.
+		/* first test if the command can be executed. */
 		res = proc(tile, flags, p1, p2);
 		if (CmdFailed(res)) {
 			if (res & 0xFFFF) _error_message = res & 0xFFFF;
 			goto show_error;
 		}
-		// no money? Only check if notest is off
+		/* no money? Only check if notest is off */
 		if (!notest && res != 0 && !CheckPlayerHasMoney(res)) goto show_error;
 	}
 
@@ -514,7 +516,7 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 	}
 #endif /* ENABLE_NETWORK */
 
-	// update last build coordinate of player.
+	/* update last build coordinate of player. */
 	if (tile != 0 && IsValidPlayer(_current_player)) {
 		GetPlayer(_current_player)->last_build_coordinate = tile;
 	}
@@ -524,8 +526,8 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 	_yearly_expenses_type = EXPENSES_CONSTRUCTION;
 	res2 = proc(tile, flags | DC_EXEC, p1, p2);
 
-	// If notest is on, it means the result of the test can be different than
-	//   the real command.. so ignore the test
+	/* If notest is on, it means the result of the test can be different than
+	 *  the real command.. so ignore the test */
 	if (!notest && !((cmd & CMD_NO_TEST_IF_IN_NETWORK) && _networking)) {
 		assert(res == res2); // sanity check
 	} else {
@@ -553,7 +555,7 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 	return true;
 
 show_error:
-	// show error message if the command fails?
+	/* show error message if the command fails? */
 	if (IsLocalPlayer() && error_part1 != 0) {
 		ShowErrorMessage(_error_message, error_part1, x,y);
 	}
diff --git a/src/command.h b/src/command.h
index 5f6c17e53..9f5a744b3 100644
--- a/src/command.h
+++ b/src/command.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file command.h */
+
 #ifndef COMMAND_H
 #define COMMAND_H
 
@@ -122,8 +124,8 @@ enum {
 	CMD_MONEY_CHEAT                  = 102,
 	CMD_BUILD_CANAL                  = 103,
 
-	CMD_PLAYER_CTRL                  = 104, // used in multiplayer to create a new player etc.
-	CMD_LEVEL_LAND                   = 105, // level land
+	CMD_PLAYER_CTRL                  = 104, ///< used in multiplayer to create a new player etc.
+	CMD_LEVEL_LAND                   = 105, ///< level land
 
 	CMD_REFIT_RAIL_VEHICLE           = 106,
 	CMD_RESTORE_ORDER_INDEX          = 107,
@@ -145,13 +147,13 @@ enum {
 
 enum {
 	DC_EXEC            = 0x01,
-	DC_AUTO            = 0x02, // don't allow building on structures
-	DC_QUERY_COST      = 0x04, // query cost only,  don't build.
-	DC_NO_WATER        = 0x08, // don't allow building on water
-	DC_NO_RAIL_OVERLAP = 0x10, // don't allow overlap of rails (used in buildrail)
-	DC_AI_BUILDING     = 0x20, // special building rules for AI
-	DC_NO_TOWN_RATING  = 0x40, // town rating does not disallow you from building
-	DC_FORCETEST       = 0x80, // force test too.
+	DC_AUTO            = 0x02, ///< don't allow building on structures
+	DC_QUERY_COST      = 0x04, ///< query cost only,  don't build.
+	DC_NO_WATER        = 0x08, ///< don't allow building on water
+	DC_NO_RAIL_OVERLAP = 0x10, ///< don't allow overlap of rails (used in buildrail)
+	DC_AI_BUILDING     = 0x20, ///< special building rules for AI
+	DC_NO_TOWN_RATING  = 0x40, ///< town rating does not disallow you from building
+	DC_FORCETEST       = 0x80, ///< force test too.
 
 	CMD_ERROR = ((int32)0x80000000),
 };
@@ -161,17 +163,15 @@ enum {
 enum {
 	CMD_AUTO                  = 0x0200,
 	CMD_NO_WATER              = 0x0400,
-	CMD_NETWORK_COMMAND       = 0x0800, // execute the command without sending it on the network
-	CMD_NO_TEST_IF_IN_NETWORK = 0x1000, // When enabled, the command will bypass the no-DC_EXEC round if in network
+	CMD_NETWORK_COMMAND       = 0x0800, ///< execute the command without sending it on the network
+	CMD_NO_TEST_IF_IN_NETWORK = 0x1000, ///< When enabled, the command will bypass the no-DC_EXEC round if in network
 	CMD_SHOW_NO_ERROR         = 0x2000,
 };
 
-/** Command flags for the command table
- * @see _command_proc_table
- */
+/** Command flags for the command table _command_proc_table */
 enum {
-	CMD_SERVER  = 0x1, /// the command can only be initiated by the server
-	CMD_OFFLINE = 0x2, /// the command cannot be executed in a multiplayer game; single-player only
+	CMD_SERVER  = 0x1, ///< the command can only be initiated by the server
+	CMD_OFFLINE = 0x2, ///< the command cannot be executed in a multiplayer game; single-player only
 };
 
 typedef int32 CommandProc(TileIndex tile, uint32 flags, uint32 p1, uint32 p2);
@@ -191,11 +191,11 @@ typedef struct Command {
  */
 static inline bool CmdFailed(int32 res)
 {
-	// lower 16bits are the StringID of the possible error
+	/* lower 16bits are the StringID of the possible error */
 	return res <= (CMD_ERROR | INVALID_STRING_ID);
 }
 
-/* command.c */
+/* command.cpp */
 typedef void CommandCallback(bool success, TileIndex tile, uint32 p1, uint32 p2);
 int32 DoCommand(TileIndex tile, uint32 p1, uint32 p2, uint32 flags, uint procc);
 bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback, uint32 cmd);
@@ -205,7 +205,7 @@ bool DoCommandP(TileIndex tile, uint32 p1, uint32 p2, CommandCallback *callback,
 void NetworkSend_Command(TileIndex tile, uint32 p1, uint32 p2, uint32 cmd, CommandCallback *callback);
 #endif /* ENABLE_NETWORK */
 
-extern const char* _cmd_text; // Text, which gets sent with a command
+extern const char* _cmd_text; ///< Text, which gets sent with a command
 
 bool IsValidCommand(uint cmd);
 byte GetCommandFlags(uint cmd);
diff --git a/src/console.cpp b/src/console.cpp
index 14d0a5772..a1fd60e74 100644
--- a/src/console.cpp
+++ b/src/console.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file console.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
@@ -26,23 +28,23 @@
 #define ICON_MAX_ALIAS_LINES 40
 #define ICON_TOKEN_COUNT 20
 
-// ** main console ** //
+/* ** main console ** */
 static char *_iconsole_buffer[ICON_BUFFER + 1];
 static uint16 _iconsole_cbuffer[ICON_BUFFER + 1];
 static Textbuf _iconsole_cmdline;
 
-// ** stdlib ** //
+/* ** stdlib ** */
 byte _stdlib_developer = 1;
 bool _stdlib_con_developer = false;
 FILE *_iconsole_output_file;
 
-// ** main console cmd buffer
+/* ** main console cmd buffer ** */
 static char *_iconsole_history[ICON_HISTORY_SIZE];
 static byte _iconsole_historypos;
 
-/* *************** */
-/*  end of header  */
-/* *************** */
+/* *************** *
+ *  end of header  *
+ * *************** */
 
 static void IConsoleClearCommand(void)
 {
@@ -60,7 +62,7 @@ static inline void IConsoleResetHistoryPos(void) {_iconsole_historypos = ICON_HI
 static void IConsoleHistoryAdd(const char *cmd);
 static void IConsoleHistoryNavigate(int direction);
 
-// ** console window ** //
+/* ** console window ** */
 static void IConsoleWndProc(Window *w, WindowEvent *e)
 {
 	static byte iconsole_scroll = ICON_BUFFER;
@@ -254,7 +256,7 @@ static void IConsoleClear(void)
 static void IConsoleWriteToLogFile(const char *string)
 {
 	if (_iconsole_output_file != NULL) {
-		// if there is an console output file ... also print it there
+		/* if there is an console output file ... also print it there */
 		fwrite(string, strlen(string), 1, _iconsole_output_file);
 		fwrite("\n", 1, 1, _iconsole_output_file);
 	}
@@ -340,7 +342,7 @@ static void IConsoleHistoryNavigate(int direction)
 {
 	int i = _iconsole_historypos + direction;
 
-	// watch out for overflows, just wrap around
+	/* watch out for overflows, just wrap around */
 	if (i < 0) i = ICON_HISTORY_SIZE - 1;
 	if (i >= ICON_HISTORY_SIZE) i = 0;
 
@@ -353,7 +355,7 @@ static void IConsoleHistoryNavigate(int direction)
 
 	_iconsole_historypos = i;
 	IConsoleClearCommand();
-	// copy history to 'command prompt / bash'
+	/* copy history to 'command prompt / bash' */
 	assert(_iconsole_history[i] != NULL && IS_INT_INSIDE(i, 0, ICON_HISTORY_SIZE));
 	ttd_strlcpy(_iconsole_cmdline.buf, _iconsole_history[i], _iconsole_cmdline.maxlength);
 	UpdateTextBufferSize(&_iconsole_cmdline);
@@ -481,9 +483,10 @@ bool GetArgumentInteger(uint32 *value, const char *arg)
 	return arg != endptr;
 }
 
-// * ************************* * //
-// * hooking code              * //
-// * ************************* * //
+/*  * *************************
+    * hooking code            *
+    * *************************/
+
 /**
  * General internal hooking code that is the same for both commands and variables
  * @param hooks @IConsoleHooks structure that will be set according to
@@ -709,18 +712,18 @@ static void IConsoleAliasExec(const IConsoleAlias *alias, byte tokencount, char
 		if (a_index >= lengthof(aliases) || astream_i >= lengthof(aliasstream)) break;
 
 		switch (*cmdptr) {
-		case '\'': /* ' will double for "" */
+		case '\'': // ' will double for ""
 			aliasstream[astream_i++] = '"';
 			break;
-		case ';': /* Cmd seperator, start new command */
+		case ';': // Cmd seperator, start new command
 			aliasstream[astream_i] = '\0';
 			aliases[++a_index] = &aliasstream[++astream_i];
 			cmdptr++;
 			break;
-		case '%': /* Some or all parameters */
+		case '%': // Some or all parameters
 			cmdptr++;
 			switch (*cmdptr) {
-			case '+': { /* All parameters seperated: "[param 1]" "[param 2]" */
+			case '+': { // All parameters seperated: "[param 1]" "[param 2]"
 				for (i = 0; i != tokencount; i++) {
 					aliasstream[astream_i++] = '"';
 					astream_i += IConsoleCopyInParams(&aliasstream[astream_i], tokens[i], astream_i);
@@ -728,7 +731,7 @@ static void IConsoleAliasExec(const IConsoleAlias *alias, byte tokencount, char
 					aliasstream[astream_i++] = ' ';
 				}
 			} break;
-			case '!': { /* Merge the parameters to one: "[param 1] [param 2] [param 3...]" */
+			case '!': { // Merge the parameters to one: "[param 1] [param 2] [param 3...]"
 				aliasstream[astream_i++] = '"';
 				for (i = 0; i != tokencount; i++) {
 					astream_i += IConsoleCopyInParams(&aliasstream[astream_i], tokens[i], astream_i);
@@ -737,7 +740,7 @@ static void IConsoleAliasExec(const IConsoleAlias *alias, byte tokencount, char
 				aliasstream[astream_i++] = '"';
 
 			} break;
-				default: { /* One specific parameter: %A = [param 1] %B = [param 2] ... */
+				default: { // One specific parameter: %A = [param 1] %B = [param 2] ...
 				int param = *cmdptr - 'A';
 
 				if (param < 0 || param >= tokencount) {
@@ -1086,16 +1089,16 @@ void IConsoleCmdExec(const char *cmdstr)
 
 			tstream_i++;
 			break;
-		case '"': /* Tokens enclosed in "" are one token */
+		case '"': // Tokens enclosed in "" are one token
 			longtoken = !longtoken;
 			break;
-		case '\\': /* Escape character for "" */
+		case '\\': // Escape character for ""
 			if (cmdptr[1] == '"' && tstream_i + 1 < lengthof(tokenstream)) {
 				tokenstream[tstream_i++] = *++cmdptr;
 				break;
 			}
 			/* fallthrough */
-		default: /* Normal character */
+		default: // Normal character
 			tokenstream[tstream_i++] = *cmdptr;
 
 			if (!foundtoken) {
diff --git a/src/console.h b/src/console.h
index ef8063bc8..da672a5b5 100644
--- a/src/console.h
+++ b/src/console.h
@@ -1,11 +1,13 @@
 /* $Id$ */
 
+/** @file console.h */
+
 #ifndef CONSOLE_H
 #define CONSOLE_H
 
-// maximum length of a typed in command
+/* maximum length of a typed in command */
 #define ICON_CMDLN_SIZE 255
-// maximum length of a totally expanded command
+/* maximum length of a totally expanded command */
 #define ICON_MAX_STREAMSIZE 1024
 
 typedef enum IConsoleVarTypes {
@@ -37,9 +39,9 @@ typedef enum IConsoleHookTypes {
  */
 typedef bool IConsoleHook(void);
 typedef struct IConsoleHooks{
-	IConsoleHook *access; // trigger when accessing the variable/command
-	IConsoleHook *pre;    // trigger before the variable/command is changed/executed
-	IConsoleHook *post;   // trigger after the variable/command is changed/executed
+	IConsoleHook *access; ///< trigger when accessing the variable/command
+	IConsoleHook *pre;    ///< trigger before the variable/command is changed/executed
+	IConsoleHook *post;   ///< trigger after the variable/command is changed/executed
 } IConsoleHooks;
 
 /** --Commands--
@@ -53,11 +55,11 @@ typedef bool (IConsoleCmdProc)(byte argc, char *argv[]);
 
 struct IConsoleCmd;
 typedef struct IConsoleCmd {
-	char *name;               // name of command
-	struct IConsoleCmd *next; // next command in list
+	char *name;               ///< name of command
+	struct IConsoleCmd *next; ///< next command in list
 
-	IConsoleCmdProc *proc;    // process executed when command is typed
-	IConsoleHooks hook;       // any special trigger action that needs executing
+	IConsoleCmdProc *proc;    ///< process executed when command is typed
+	IConsoleHooks hook;       ///< any special trigger action that needs executing
 } IConsoleCmd;
 
 /** --Variables--
@@ -71,15 +73,15 @@ typedef struct IConsoleCmd {
  */
 struct IConsoleVar;
 typedef struct IConsoleVar {
-	char *name;               // name of the variable
-	struct IConsoleVar *next; // next variable in list
-
-	void *addr;               // the address where the variable is pointing at
-	uint32 size;              // size of the variable, used for strings
-	char *help;               // the optional help string shown when requesting information
-	IConsoleVarTypes type;    // type of variable (for correct assignment/output)
-	IConsoleCmdProc *proc;    // some variables need really special handling, use a callback function for that
-	IConsoleHooks hook;       // any special trigger action that needs executing
+	char *name;               ///< name of the variable
+	struct IConsoleVar *next; ///< next variable in list
+
+	void *addr;               ///< the address where the variable is pointing at
+	uint32 size;              ///< size of the variable, used for strings
+	char *help;               ///< the optional help string shown when requesting information
+	IConsoleVarTypes type;    ///< type of variable (for correct assignment/output)
+	IConsoleCmdProc *proc;    ///< some variables need really special handling, use a callback function for that
+	IConsoleHooks hook;       ///< any special trigger action that needs executing
 } IConsoleVar;
 
 /** --Aliases--
@@ -95,16 +97,16 @@ typedef struct IConsoleVar {
  */
 struct IConsoleAlias;
 typedef struct IConsoleAlias {
-	char *name;                 // name of the alias
-	struct IConsoleAlias *next; // next alias in list
+	char *name;                 ///< name of the alias
+	struct IConsoleAlias *next; ///< next alias in list
 
-	char *cmdline;              // command(s) that is/are being aliased
+	char *cmdline;              ///< command(s) that is/are being aliased
 } IConsoleAlias;
 
 /* console parser */
-VARDEF IConsoleCmd   *_iconsole_cmds;    // list of registred commands
-VARDEF IConsoleVar   *_iconsole_vars;    // list of registred vars
-VARDEF IConsoleAlias *_iconsole_aliases; // list of registred aliases
+VARDEF IConsoleCmd   *_iconsole_cmds;    ///< list of registred commands
+VARDEF IConsoleVar   *_iconsole_vars;    ///< list of registred vars
+VARDEF IConsoleAlias *_iconsole_aliases; ///< list of registred aliases
 
 /* console colors/modes */
 VARDEF byte _icolour_def;
diff --git a/src/console_cmds.cpp b/src/console_cmds.cpp
index 21012e458..5edde43be 100644
--- a/src/console_cmds.cpp
+++ b/src/console_cmds.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file console_cmds.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "console.h"
@@ -226,7 +228,7 @@ static const FiosItem* GetFiosItem(const char* file)
 		if (strcmp(file, _fios_list[i].title) == 0) break;
 	}
 
-	if (i == _fios_num) { /* If no name matches, try to parse it as number */
+	if (i == _fios_num) { // If no name matches, try to parse it as number
 		char* endptr;
 
 		i = strtol(file, &endptr, 10);
@@ -614,7 +616,7 @@ DEF_CONSOLE_HOOK(ConHookValidateMaxCompaniesCount)
 
 DEF_CONSOLE_HOOK(ConHookValidateMaxSpectatorsCount)
 {
-	/* XXX @see ConHookValidateMaxClientsCount */
+	/* XXX see ConHookValidateMaxClientsCount */
 	if (_network_game_info.spectators_max > 10) {
 		_network_game_info.spectators_max = 10;
 		IConsoleError("Maximum spectators out of bounds, truncating to limit.");
@@ -1342,7 +1344,7 @@ DEF_CONSOLE_HOOK(ConProcPlayerName)
 
 	if (ci == NULL) return false;
 
-	// Don't change the name if it is the same as the old name
+	/* Don't change the name if it is the same as the old name */
 	if (strcmp(ci->client_name, _network_player_name) != 0) {
 		if (!_network_server) {
 			SEND_COMMAND(PACKET_CLIENT_SET_NAME)(_network_player_name);
@@ -1441,8 +1443,8 @@ DEF_CONSOLE_CMD(ConListDumpVariables)
 
 static void IConsoleDebugLibRegister(void)
 {
-	// debugging variables and functions
-	extern bool _stdlib_con_developer; /* XXX extern in .c */
+	/* debugging variables and functions */
+	extern bool _stdlib_con_developer; // XXX extern in .cpp
 
 	IConsoleVarRegister("con_developer",    &_stdlib_con_developer, ICONSOLE_VAR_BOOLEAN, "Enable/disable console debugging information (internal)");
 	IConsoleCmdRegister("resettile",        ConResetTile);
@@ -1458,10 +1460,10 @@ static void IConsoleDebugLibRegister(void)
 
 void IConsoleStdLibRegister(void)
 {
-	// stdlib
-	extern byte _stdlib_developer; /* XXX extern in .c */
+	/* stdlib */
+	extern byte _stdlib_developer; // XXX extern in .cpp
 
-	// default variables and functions
+	/* default variables and functions */
 	IConsoleCmdRegister("debug_level",  ConDebugLevel);
 	IConsoleCmdRegister("dump_vars",    ConListDumpVariables);
 	IConsoleCmdRegister("echo",         ConEcho);
diff --git a/src/currency.cpp b/src/currency.cpp
index 7bc81139a..036f827bd 100644
--- a/src/currency.cpp
+++ b/src/currency.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file currency.cpp **/
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "currency.h"
@@ -13,34 +15,34 @@
 	//   |   |    Euro year  |       |       |    name
 	//   |   |    |          |       |       |    |
 static const CurrencySpec origin_currency_specs[NUM_CURRENCY] = {
-	{    1, ',', CF_NOEURO, "£",    "",      0,  STR_CURR_GBP    }, // british pounds
-	{    2, ',', CF_NOEURO, "$",    "",      0,  STR_CURR_USD    }, // us dollars
-	{    2, ',', CF_ISEURO, "€",    "",      0,  STR_CURR_EUR    }, // Euro
-	{  220, ',', CF_NOEURO, "¥",    "",      0,  STR_CURR_YEN    }, // yen
-	{   20, ',', 2002,      "",     " S.",   1,  STR_CURR_ATS    }, // austrian schilling
-	{   59, ',', 2002,      "BEF ", "",      0,  STR_CURR_BEF    }, // belgian franc
-	{    2, ',', CF_NOEURO, "CHF ", "",      0,  STR_CURR_CHF    }, // swiss franc
-	{   41, ',', CF_NOEURO, "",     " Kč",   1,  STR_CURR_CZK    }, // czech koruna
-	{    3, '.', 2002,      "DM ",  "",      0,  STR_CURR_DEM    }, // deutsche mark
-	{   11, '.', CF_NOEURO, "",     " kr",   1,  STR_CURR_DKK    }, // danish krone
-	{  245, '.', 2002,      "Pts ", "",      0,  STR_CURR_ESP    }, // spanish pesetas
-	{    9, ',', 2002,      "",     " mk",   1,  STR_CURR_FIM    }, // finnish markka
-	{   10, '.', 2002,      "FF ",  "",      0,  STR_CURR_FRF    }, // french francs
-	{  500, ',', 2002,      "",     "Dr.",   1,  STR_CURR_GRD    }, // greek drachma
-	{  378, ',', 2010,      "",     " Ft",   1,  STR_CURR_HUF    }, // hungarian forint
-	{  130, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_ISK    }, // icelandic krona
-	{ 2850, ',', 2002,      "",     " L.",   1,  STR_CURR_ITL    }, // italian lira
-	{    3, ',', 2002,      "NLG ", "",      0,  STR_CURR_NLG    }, // dutch gulden
-	{   12, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_NOK    }, // norwegian krone
-	{    6, ' ', CF_NOEURO, "",     " zl",   1,  STR_CURR_PLN    }, // polish zloty
-	{    5, '.', CF_NOEURO, "",     " Lei",  1,  STR_CURR_ROL    }, // romanian Lei
-	{   50, ' ', CF_NOEURO, "",     " p",    1,  STR_CURR_RUR    }, // russian rouble
-	{  352, '.', CF_NOEURO, "",     " SIT",  1,  STR_CURR_SIT    }, // slovenian tolar
-	{   13, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_SEK    }, // swedish krona
-	{    3, '.', CF_NOEURO, "",     " YTL",  1,  STR_CURR_YTL    }, // turkish lira
-	{   52, ',', CF_NOEURO, "",     " Sk",   1,  STR_CURR_SKK    }, // slovak koruna
-	{    4, ',', CF_NOEURO, "R$ ",  "",      0,  STR_CURR_BRR    }, // brazil real
-	{    1, ' ', CF_NOEURO, "",     "",      2,  STR_CURR_CUSTOM }, // custom currency
+	{    1, ',', CF_NOEURO, "£",    "",      0,  STR_CURR_GBP    }, ///< british pounds
+	{    2, ',', CF_NOEURO, "$",    "",      0,  STR_CURR_USD    }, ///< us dollars
+	{    2, ',', CF_ISEURO, "€",    "",      0,  STR_CURR_EUR    }, ///< Euro
+	{  220, ',', CF_NOEURO, "¥",    "",      0,  STR_CURR_YEN    }, ///< yen
+	{   20, ',', 2002,      "",     " S.",   1,  STR_CURR_ATS    }, ///< austrian schilling
+	{   59, ',', 2002,      "BEF ", "",      0,  STR_CURR_BEF    }, ///< belgian franc
+	{    2, ',', CF_NOEURO, "CHF ", "",      0,  STR_CURR_CHF    }, ///< swiss franc
+	{   41, ',', CF_NOEURO, "",     " Kč",   1,  STR_CURR_CZK    }, ///< czech koruna
+	{    3, '.', 2002,      "DM ",  "",      0,  STR_CURR_DEM    }, ///< deutsche mark
+	{   11, '.', CF_NOEURO, "",     " kr",   1,  STR_CURR_DKK    }, ///< danish krone
+	{  245, '.', 2002,      "Pts ", "",      0,  STR_CURR_ESP    }, ///< spanish pesetas
+	{    9, ',', 2002,      "",     " mk",   1,  STR_CURR_FIM    }, ///< finnish markka
+	{   10, '.', 2002,      "FF ",  "",      0,  STR_CURR_FRF    }, ///< french francs
+	{  500, ',', 2002,      "",     "Dr.",   1,  STR_CURR_GRD    }, ///< greek drachma
+	{  378, ',', 2010,      "",     " Ft",   1,  STR_CURR_HUF    }, ///< hungarian forint
+	{  130, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_ISK    }, ///< icelandic krona
+	{ 2850, ',', 2002,      "",     " L.",   1,  STR_CURR_ITL    }, ///< italian lira
+	{    3, ',', 2002,      "NLG ", "",      0,  STR_CURR_NLG    }, ///< dutch gulden
+	{   12, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_NOK    }, ///< norwegian krone
+	{    6, ' ', CF_NOEURO, "",     " zl",   1,  STR_CURR_PLN    }, ///< polish zloty
+	{    5, '.', CF_NOEURO, "",     " Lei",  1,  STR_CURR_ROL    }, ///< romanian Lei
+	{   50, ' ', CF_NOEURO, "",     " p",    1,  STR_CURR_RUR    }, ///< russian rouble
+	{  352, '.', CF_NOEURO, "",     " SIT",  1,  STR_CURR_SIT    }, ///< slovenian tolar
+	{   13, '.', CF_NOEURO, "",     " Kr",   1,  STR_CURR_SEK    }, ///< swedish krona
+	{    3, '.', CF_NOEURO, "",     " YTL",  1,  STR_CURR_YTL    }, ///< turkish lira
+	{   52, ',', CF_NOEURO, "",     " Sk",   1,  STR_CURR_SKK    }, ///< slovak koruna
+	{    4, ',', CF_NOEURO, "R$ ",  "",      0,  STR_CURR_BRR    }, ///< brazil real
+	{    1, ' ', CF_NOEURO, "",     "",      2,  STR_CURR_CUSTOM }, ///< custom currency
 };
 
 /* Array of currencies used by the system */
@@ -122,7 +124,10 @@ byte GetNewgrfCurrencyIdConverted(byte grfcurr_id)
 	return (grfcurr_id >= lengthof(TTDPatch_To_OTTDIndex)) ? grfcurr_id : TTDPatch_To_OTTDIndex[grfcurr_id];
 }
 
-/* get a mask of the allowed currencies depending on the year */
+/**
+ * get a mask of the allowed currencies depending on the year
+ * @return mask of currencies
+ */
 uint GetMaskOfAllowedCurrencies(void)
 {
 	uint mask = 0;
diff --git a/src/currency.h b/src/currency.h
index 40fb553a4..ccfed57c4 100644
--- a/src/currency.h
+++ b/src/currency.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file currency.h */
+
 #ifndef CURRENCY_H
 #define CURRENCY_H