(svn r9556) -Documentation: doxygen and comment-style changes. 'R', 'S'.. The end of the preliminary work is near

37 files changed, 452 insertions, 359 deletions

diff --git a/src/rail.cpp b/src/rail.cpp
index 8fefaa399..6cd97b170 100644
--- a/src/rail.cpp
+++ b/src/rail.cpp
@@ -81,7 +81,7 @@ extern const Trackdir _track_exitdir_to_trackdir[][DIAGDIR_END] = {
 	{TRACKDIR_RIGHT_N,  TRACKDIR_RIGHT_S,  INVALID_TRACKDIR,  INVALID_TRACKDIR}
 };
 
-extern const Trackdir _track_enterdir_to_trackdir[][DIAGDIR_END] = { // TODO: replace magic with enums
+extern const Trackdir _track_enterdir_to_trackdir[][DIAGDIR_END] = {
 	{TRACKDIR_X_NE,     INVALID_TRACKDIR,  TRACKDIR_X_SW,     INVALID_TRACKDIR},
 	{INVALID_TRACKDIR,  TRACKDIR_Y_SE,     INVALID_TRACKDIR,  TRACKDIR_Y_NW},
 	{INVALID_TRACKDIR,  TRACKDIR_UPPER_E,  TRACKDIR_UPPER_W,  INVALID_TRACKDIR},
diff --git a/src/rail.h b/src/rail.h
index 20cc15ce3..52139b69a 100644
--- a/src/rail.h
+++ b/src/rail.h
@@ -223,7 +223,7 @@ struct RailtypeInfo {
 	 * 1) All the sprites in a railset MUST be in the same order. This order
 	 *    is determined by normal rail. Check sprites 1005 and following for this order<p>
 	 * 2) The position where the railtype is loaded must always be the same, otherwise
-	 *    the offset will fail.<p>
+	 *    the offset will fail.
 	 * @note: Something more flexible might be desirable in the future.
 	 */
 	SpriteID total_offset;
@@ -240,10 +240,10 @@ struct RailtypeInfo {
 };
 
 
-// these are the maximums used for updating signal blocks, and checking if a depot is in a pbs block
+/** these are the maximums used for updating signal blocks, and checking if a depot is in a pbs block */
 enum {
-	NUM_SSD_ENTRY = 256, // max amount of blocks
-	NUM_SSD_STACK =  32, // max amount of blocks to check recursively
+	NUM_SSD_ENTRY = 256, ///< max amount of blocks
+	NUM_SSD_STACK =  32, ///< max amount of blocks to check recursively
 };
 
 /**
diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp
index 308aa8efd..05100a9ad 100644
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -79,8 +79,8 @@ const byte _track_sloped_sprites[14] = {
 
 static bool CheckTrackCombination(TileIndex tile, TrackBits to_build, uint flags)
 {
-	TrackBits current; /* The current track layout */
-	TrackBits future; /* The track layout we want to build */
+	TrackBits current; // The current track layout
+	TrackBits future;  // The track layout we want to build
 	_error_message = STR_1001_IMPOSSIBLE_TRACK_COMBINATION;
 
 	if (!IsPlainRailTile(tile)) return false;
@@ -111,7 +111,7 @@ static bool CheckTrackCombination(TileIndex tile, TrackBits to_build, uint flags
 
 static const TrackBits _valid_tileh_slopes[][15] = {
 
-// set of normal ones
+/* set of normal ones */
 {
 	TRACK_BIT_ALL,
 	TRACK_BIT_RIGHT,
@@ -133,7 +133,7 @@ static const TrackBits _valid_tileh_slopes[][15] = {
 	TRACK_BIT_RIGHT,
 },
 
-// allowed rail for an evenly raised platform
+/* allowed rail for an evenly raised platform */
 {
 	TRACK_BIT_NONE,
 	TRACK_BIT_LEFT,
@@ -199,13 +199,13 @@ static uint32 CheckRailSlope(Slope tileh, TrackBits rail_bits, TrackBits existin
 	} else {
 		rail_bits |= existing;
 
-		// don't allow building on the lower side of a coast
+		/* don't allow building on the lower side of a coast */
 		if (IsTileType(tile, MP_WATER) &&
 				~_valid_tileh_slopes[1][tileh] & rail_bits) {
 			return_cmd_error(STR_3807_CAN_T_BUILD_ON_WATER);
 		}
 
-		// no special foundation
+		/* no special foundation */
 		if ((~_valid_tileh_slopes[0][tileh] & rail_bits) == 0)
 			return 0;
 
@@ -259,7 +259,7 @@ int32 CmdBuildSingleRail(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			}
 			if (!IsTileOwner(tile, _current_player) ||
 					!IsCompatibleRail(GetRailType(tile), railtype)) {
-				// Get detailed error message
+				/* Get detailed error message */
 				return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 			}
 
@@ -434,11 +434,11 @@ static int32 ValidateAutoDrag(Trackdir *trackdir, TileIndex start, TileIndex end
 
 	if (!ValParamTrackOrientation(TrackdirToTrack(*trackdir))) return CMD_ERROR;
 
-	// calculate delta x,y from start to end tile
+	/* calculate delta x,y from start to end tile */
 	dx = ex - x;
 	dy = ey - y;
 
-	// calculate delta x,y for the first direction
+	/* calculate delta x,y for the first direction */
 	trdx = _trackdelta[*trackdir].x;
 	trdy = _trackdelta[*trackdir].y;
 
@@ -447,7 +447,7 @@ static int32 ValidateAutoDrag(Trackdir *trackdir, TileIndex start, TileIndex end
 		trdy += _trackdelta[*trackdir ^ 1].y;
 	}
 
-	// validate the direction
+	/* validate the direction */
 	while (
 		(trdx <= 0 && dx > 0) ||
 		(trdx >= 0 && dx < 0) ||
@@ -463,8 +463,8 @@ static int32 ValidateAutoDrag(Trackdir *trackdir, TileIndex start, TileIndex end
 		}
 	}
 
-	// (for diagonal tracks, this is already made sure of by above test), but:
-	// for non-diagonal tracks, check if the start and end tile are on 1 line
+	/* (for diagonal tracks, this is already made sure of by above test), but:
+	 * for non-diagonal tracks, check if the start and end tile are on 1 line */
 	if (!IsDiagonalTrackdir(*trackdir)) {
 		trdx = _trackdelta[*trackdir].x;
 		trdy = _trackdelta[*trackdir].y;
@@ -517,7 +517,7 @@ static int32 CmdRailTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint32
 
 		tile += ToTileIndexDiff(_trackdelta[trackdir]);
 
-		// toggle railbit for the non-diagonal tracks
+		/* toggle railbit for the non-diagonal tracks */
 		if (!IsDiagonalTrackdir(trackdir)) ToggleBitT(trackdir, 0);
 	}
 
@@ -649,11 +649,11 @@ int32 CmdBuildSingleSignal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	SET_EXPENSES_TYPE(EXPENSES_CONSTRUCTION);
 
 	if (!HasSignalOnTrack(tile, track)) {
-		// build new signals
+		/* build new signals */
 		cost = _price.build_signals;
 	} else {
 		if (p2 != 0 && sigvar != GetSignalVariant(tile)) {
-			// convert signals <-> semaphores
+			/* convert signals <-> semaphores */
 			cost = _price.build_signals + _price.remove_signals;
 		} else {
 			// it is free to change orientation/pre-exit-combo signals
@@ -663,21 +663,21 @@ int32 CmdBuildSingleSignal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 	if (flags & DC_EXEC) {
 		if (!HasSignals(tile)) {
-			// there are no signals at all on this tile yet
+			/* there are no signals at all on this tile yet */
 			SetHasSignals(tile, true);
 			_m[tile].m2 |= 0xF0;              // all signals are on
-			_m[tile].m3 &= ~0xF0;          // no signals built by default
+			_m[tile].m3 &= ~0xF0;             // no signals built by default
 			SetSignalType(tile, SIGTYPE_NORMAL);
 			SetSignalVariant(tile, sigvar);
 		}
 
 		if (p2 == 0) {
 			if (!HasSignalOnTrack(tile, track)) {
-				// build new signals
+				/* build new signals */
 				_m[tile].m3 |= SignalOnTrack(track);
 			} else {
 				if (pre_signal) {
-					// cycle between normal -> pre -> exit -> combo -> ...
+					/* cycle between normal -> pre -> exit -> combo -> ... */
 					SignalType type = GetSignalType(tile);
 
 					SetSignalType(tile, type == SIGTYPE_COMBO ? SIGTYPE_NORMAL : (SignalType)(type + 1));
@@ -746,7 +746,7 @@ static int32 CmdSignalTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint3
 		signals = _m[tile].m3 & SignalOnTrack(track);
 		if (signals == 0) signals = SignalOnTrack(track); /* Can this actually occur? */
 
-		// copy signal/semaphores style (independent of CTRL)
+		/* copy signal/semaphores style (independent of CTRL) */
 		semaphores = GetSignalVariant(tile) != SIG_ELECTRIC;
 	} else { // no signals exist, drag a two-way signal stretch
 		signals = SignalOnTrack(track);
@@ -762,7 +762,7 @@ static int32 CmdSignalTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint3
 	 * remove     - 1 remove signals, 0 build signals */
 	signal_ctr = total_cost = 0;
 	for (;;) {
-		// only build/remove signals with the specified density
+		/* only build/remove signals with the specified density */
 		if (signal_ctr % signal_density == 0) {
 			uint32 p1 = GB(TrackdirToTrack(trackdir), 0, 3);
 			SB(p1, 3, 1, mode);
@@ -781,7 +781,7 @@ static int32 CmdSignalTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint3
 		tile += ToTileIndexDiff(_trackdelta[trackdir]);
 		signal_ctr++;
 
-		// toggle railbit for the non-diagonal tracks (|, -- tracks)
+		/* toggle railbit for the non-diagonal tracks (|, -- tracks) */
 		if (!IsDiagonalTrackdir(trackdir)) ToggleBitT(trackdir, 0);
 	}
 
@@ -869,15 +869,15 @@ static int32 DoConvertRail(TileIndex tile, RailType totype, bool exec)
 
 	if (!EnsureNoVehicleOnGround(tile) && (!IsCompatibleRail(GetRailType(tile), totype) || IsPlainRailTile(tile))) return CMD_ERROR;
 
-	// 'hidden' elrails can't be downgraded to normal rail when elrails are disabled
+	/* 'hidden' elrails can't be downgraded to normal rail when elrails are disabled */
 	if (_patches.disable_elrails && totype == RAILTYPE_RAIL && GetRailType(tile) == RAILTYPE_ELECTRIC) return CMD_ERROR;
 
-	// change type.
+	/* change type. */
 	if (exec) {
 		SetRailType(tile, totype);
 		MarkTileDirtyByTile(tile);
 
-		// notify YAPF about the track layout change
+		/* notify YAPF about the track layout change */
 		TrackBits tracks = GetTrackBits(tile);
 		while (tracks != TRACK_BIT_NONE) {
 			YapfNotifyTrackLayoutChange(tile, RemoveFirstTrack(&tracks));
@@ -923,7 +923,7 @@ int32 CmdConvertRail(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	if (!ValParamRailtype(p2)) return CMD_ERROR;
 	if (p1 >= MapSize()) return CMD_ERROR;
 
-	// 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);
@@ -1188,7 +1188,7 @@ static void DrawTrackBits(TileInfo* ti, TrackBits track)
 	SpriteID pal = PAL_NONE;
 	bool junction = false;
 
-	// Select the sprite to use.
+	/* Select the sprite to use. */
 	(image = rti->base_sprites.track_y, track == TRACK_BIT_Y) ||
 	(image++,                           track == TRACK_BIT_X) ||
 	(image++,                           track == TRACK_BIT_UPPER) ||
@@ -1212,8 +1212,8 @@ static void DrawTrackBits(TileInfo* ti, TrackBits track)
 
 		if (foundation != 0) DrawFoundation(ti, foundation);
 
-		// DrawFoundation() modifies ti.
-		// Default sloped sprites..
+		/* DrawFoundation() modifies it.
+		 * Default sloped sprites.. */
 		if (ti->tileh != SLOPE_FLAT)
 			image = _track_sloped_sprites[ti->tileh - 1] + rti->base_sprites.track_y;
 	}
@@ -1226,7 +1226,7 @@ static void DrawTrackBits(TileInfo* ti, TrackBits track)
 
 	DrawGroundSprite(image, pal);
 
-	// Draw track pieces individually for junction tiles
+	/* Draw track pieces individually for junction tiles */
 	if (junction) {
 		if (track & TRACK_BIT_X)     DrawGroundSprite(rti->base_sprites.single_y, PAL_NONE);
 		if (track & TRACK_BIT_Y)     DrawGroundSprite(rti->base_sprites.single_x, PAL_NONE);
@@ -1288,7 +1288,7 @@ static void DrawTile_Track(TileInfo *ti)
 
 		if (HasSignals(ti->tile)) DrawSignals(ti->tile, rails);
 	} else {
-		// draw depot/waypoint
+		/* draw depot/waypoint */
 		const DrawTileSprites* dts;
 		const DrawTileSeqStruct* dtss;
 		uint32 relocation;
@@ -1303,8 +1303,8 @@ static void DrawTile_Track(TileInfo *ti)
 			image = dts->ground_sprite;
 			if (image != SPR_FLAT_GRASS_TILE) image += rti->total_offset;
 
-			// adjust ground tile for desert
-			// don't adjust for snow, because snow in depots looks weird
+			/* adjust ground tile for desert
+			 * don't adjust for snow, because snow in depots looks weird */
 			if (IsSnowRailGround(ti->tile) && _opt.landscape == LT_TROPIC) {
 				if (image != SPR_FLAT_GRASS_TILE) {
 					image += rti->snow_offset; // tile with tracks
@@ -1313,12 +1313,12 @@ static void DrawTile_Track(TileInfo *ti)
 				}
 			}
 		} else {
-			// look for customization
+			/* look for customization */
 			byte stat_id = GetWaypointByTile(ti->tile)->stat_id;
 			const StationSpec *statspec = GetCustomStationSpec(STAT_CLASS_WAYP, stat_id);
 
 			if (statspec != NULL) {
-				// emulate station tile - open with building
+				/* emulate station tile - open with building */
 				const Station* st = ComposeWaypointStation(ti->tile);
 				uint gfx = 2;
 
@@ -1348,7 +1348,7 @@ static void DrawTile_Track(TileInfo *ti)
 				}
 			} else {
 default_waypoint:
-				// There is no custom layout, fall back to the default graphics
+				/* There is no custom layout, fall back to the default graphics */
 				dts = &_waypoint_gfx_table[GetWaypointAxis(ti->tile)];
 				relocation = 0;
 				image = dts->ground_sprite + rti->total_offset;
@@ -1435,15 +1435,15 @@ struct SetSignalsData {
 	bool stop;
 	bool has_presignal;
 
-	// presignal info
+	/* presignal info */
 	int presignal_exits;
 	int presignal_exits_free;
 
-	// these are used to keep track of the signals that change.
+	/* these are used to keep track of the signals that change. */
 	TrackdirByte bit[NUM_SSD_ENTRY];
 	TileIndex tile[NUM_SSD_ENTRY];
 
-	// these are used to keep track of the stack that modifies presignals recursively
+	/* these are used to keep track of the stack that modifies presignals recursively */
 	TileIndex next_tile[NUM_SSD_STACK];
 	DiagDirectionByte next_dir[NUM_SSD_STACK];
 
@@ -1455,22 +1455,22 @@ static bool SetSignalsEnumProc(TileIndex tile, void* data, Trackdir trackdir, ui
 
 	if (!IsTileType(tile, MP_RAILWAY)) return false;
 
-	// the tile has signals?
+	/* the tile has signals? */
 	if (HasSignalOnTrack(tile, TrackdirToTrack(trackdir))) {
 		if (HasSignalOnTrackdir(tile, ReverseTrackdir(trackdir))) {
-			// yes, add the signal to the list of signals
+			/* yes, add the signal to the list of signals */
 			if (ssd->cur != NUM_SSD_ENTRY) {
 				ssd->tile[ssd->cur] = tile; // remember the tile index
 				ssd->bit[ssd->cur] = trackdir; // and the controlling bit number
 				ssd->cur++;
 			}
 
-			// remember if this block has a presignal.
+			/* remember if this block has a presignal. */
 			ssd->has_presignal |= IsPresignalEntry(tile);
 		}
 
 		if (HasSignalOnTrackdir(tile, trackdir) && IsPresignalExit(tile)) {
-			// this is an exit signal that points out from the segment
+			/* this is an exit signal that points out from the segment */
 			ssd->presignal_exits++;
 			if (GetSignalStateByTrackdir(tile, trackdir) != SIGNAL_STATE_RED)
 				ssd->presignal_exits_free++;
@@ -1528,21 +1528,21 @@ static bool SignalVehicleCheck(TileIndex tile, uint track)
 
 		dest.track = 1 << (direction & 1); // get the trackbit the vehicle would have if it has not entered the tunnel yet (ie is still visible)
 
-		// check for a vehicle with that trackdir on the start tile of the tunnel
+		/* check for a vehicle with that trackdir on the start tile of the tunnel */
 		if (VehicleFromPos(tile, &dest, SignalVehicleCheckProc) != NULL) return true;
 
-		// check for a vehicle with that trackdir on the end tile of the tunnel
+		/* check for a vehicle with that trackdir on the end tile of the tunnel */
 		if (VehicleFromPos(end, &dest, SignalVehicleCheckProc) != NULL) return true;
 
-		// now check all tiles from start to end for a warping vehicle
-		// NOTE: the hashes for tiles may overlap, so this could maybe be optimised a bit by not checking every tile?
+		/* now check all tiles from start to end for a warping vehicle
+		 * NOTE: the hashes for tiles may overlap, so this could maybe be optimised a bit by not checking every tile? */
 		dest.track = 0x40;   //Vehicle inside a tunnel or on a bridge
 		for (; tile != end; tile += TileOffsByDiagDir(direction)) {
 			if (VehicleFromPos(tile, &dest, SignalVehicleCheckProc) != NULL)
 				return true;
 		}
 
-		// no vehicle found
+		/* no vehicle found */
 		return false;
 	}
 
@@ -1597,39 +1597,39 @@ static void ChangeSignalStates(SetSignalsData *ssd)
 {
 	int i;
 
-	// thinking about presignals...
-	// the presignal is green if,
-	//   if no train is in the segment AND
-	//   there is at least one green exit signal OR
-	//   there are no exit signals in the segment
+	/* thinking about presignals...
+	 * the presignal is green if,
+	 *   if no train is in the segment AND
+	 *   there is at least one green exit signal OR
+	 *   there are no exit signals in the segment */
 
-	// then mark the signals in the segment accordingly
+	/* then mark the signals in the segment accordingly */
 	for (i = 0; i != ssd->cur; i++) {
 		TileIndex tile = ssd->tile[i];
 		byte bit = SignalAgainstTrackdir(ssd->bit[i]);
 		uint16 m2 = _m[tile].m2;
 
-		// presignals don't turn green if there is at least one presignal exit and none are free
+		/* presignals don't turn green if there is at least one presignal exit and none are free */
 		if (IsPresignalEntry(tile)) {
 			int ex = ssd->presignal_exits, exfree = ssd->presignal_exits_free;
 
-			// subtract for dual combo signals so they don't count themselves
+			/* subtract for dual combo signals so they don't count themselves */
 			if (IsPresignalExit(tile) && HasSignalOnTrackdir(tile, ssd->bit[i])) {
 				ex--;
 				if (GetSignalStateByTrackdir(tile, ssd->bit[i]) != SIGNAL_STATE_RED) exfree--;
 			}
 
-			// if we have exits and none are free, make red.
+			/* if we have exits and none are free, make red. */
 			if (ex && !exfree) goto make_red;
 		}
 
-		// check if the signal is unaffected.
+		/* check if the signal is unaffected. */
 		if (ssd->stop) {
 make_red:
-			// turn red
+			/* turn red */
 			if ((bit & m2) == 0) continue;
 		} else {
-			// turn green
+			/* turn green */
 			if ((bit & m2) != 0) continue;
 		}
 
@@ -1644,7 +1644,7 @@ make_red:
 			}
 		}
 
-		// it changed, so toggle it
+		/* it changed, so toggle it */
 		_m[tile].m2 = m2 ^ bit;
 		MarkTileDirtyByTile(tile);
 	}
@@ -1659,23 +1659,23 @@ bool UpdateSignalsOnSegment(TileIndex tile, DiagDirection direction)
 	ssd.cur_stack = 0;
 
 	for (;;) {
-		// go through one segment and update all signals pointing into that segment.
+		/* go through one segment and update all signals pointing into that segment. */
 		ssd.cur = ssd.presignal_exits = ssd.presignal_exits_free = 0;
 		ssd.has_presignal = false;
 
 		FollowTrack(tile, 0xC000 | TRANSPORT_RAIL, direction, SetSignalsEnumProc, SetSignalsAfterProc, &ssd);
 		ChangeSignalStates(&ssd);
 
-		// remember the result only for the first iteration.
+		/* remember the result only for the first iteration. */
 		if (result < 0) {
-			// stay in depot while segment is occupied or while all presignal exits are blocked
+			/* stay in depot while segment is occupied or while all presignal exits are blocked */
 			result = ssd.stop || (ssd.presignal_exits > 0 && ssd.presignal_exits_free == 0);
 		}
 
-		// if any exit signals were changed, we need to keep going to modify the stuff behind those.
+		/* if any exit signals were changed, we need to keep going to modify the stuff behind those. */
 		if (ssd.cur_stack == 0) break;
 
-		// one or more exit signals were changed, so we need to update another segment too.
+		/* one or more exit signals were changed, so we need to update another segment too. */
 		tile = ssd.next_tile[--ssd.cur_stack];
 		direction = ssd.next_dir[ssd.cur_stack];
 	}
@@ -1768,7 +1768,7 @@ static void TileLoop_Track(TileIndex tile)
 
 	new_ground = RAIL_GROUND_GRASS;
 
-	if (old_ground != RAIL_GROUND_BARREN) { /* wait until bottom is green */
+	if (old_ground != RAIL_GROUND_BARREN) { // wait until bottom is green
 		/* determine direction of fence */
 		TrackBits rail = GetTrackBits(tile);
 
@@ -1962,7 +1962,7 @@ static uint32 VehicleEnter_Track(Vehicle *v, TileIndex tile, int x, int y)
 	DiagDirection dir;
 	int length;
 
-	// this routine applies only to trains in depot tiles
+	/* this routine applies only to trains in depot tiles */
 	if (v->type != VEH_TRAIN || !IsTileDepotType(tile, TRANSPORT_RAIL)) return VETSB_CONTINUE;
 
 	/* depot direction */
diff --git a/src/saveload.cpp b/src/saveload.cpp
index e3929e946..9e3ca0768 100644
--- a/src/saveload.cpp
+++ b/src/saveload.cpp
@@ -412,8 +412,8 @@ int64 ReadValue(const void *ptr, VarType conv)
 /** Write the value of a setting
  * @param ptr pointer to the variable
  * @param conv type of variable, can be a non-clean type, eg
- * with other flags. It is parsed upon read
- * @param var the new value being given to the variable */
+ *             with other flags. It is parsed upon read
+ * @param val the new value being given to the variable */
 void WriteValue(void *ptr, VarType conv, int64 val)
 {
 	switch (GetVarMemType(conv)) {
@@ -498,6 +498,7 @@ static inline size_t SlCalcNetStringLen(const char *ptr, size_t length)
  * by SlCalcNetStringLen and the length that the index will occupy.
  * @param ptr pointer to the stringbuffer
  * @param length maximum length of the string (buffer size, etc.)
+ * @param conv type of data been used
  * @return return the gross length of the string */
 static inline size_t SlCalcStringLen(const void *ptr, size_t length, VarType conv)
 {
@@ -525,7 +526,7 @@ static inline size_t SlCalcStringLen(const void *ptr, size_t length, VarType con
 /**
  * Save/Load a string.
  * @param ptr the string being manipulated
- * @param the length of the string (full length)
+ * @param length of the string (full length)
  * @param conv must be SLE_FILE_STRING */
 static void SlString(void *ptr, size_t length, VarType conv)
 {
@@ -650,7 +651,9 @@ static inline bool SlSkipVariableOnLoad(const SaveLoad *sld)
 
 /**
  * Calculate the size of an object.
+ * @param object to be measured
  * @param sld The SaveLoad description of the object so we know how to manipulate it
+ * @return size of given objetc
  */
 static size_t SlCalcObjLength(const void *object, const SaveLoad *sld)
 {
@@ -768,7 +771,7 @@ void SlObject(void *object, const SaveLoad *sld)
 
 /**
  * Save or Load (a list of) global variables
- * @param desc The global variable that is being loaded or saved
+ * @param sldg The global variable that is being loaded or saved
  */
 void SlGlobList(const SaveLoadGlobVarList *sldg)
 {
diff --git a/src/saveload.h b/src/saveload.h
index f5bf82489..9148ab5a5 100644
--- a/src/saveload.h
+++ b/src/saveload.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file saveload.h */
+
 #ifndef SAVELOAD_H
 #define SAVELOAD_H
 
@@ -10,9 +12,9 @@
 #define SIZE_MAX ((size_t)-1)
 
 enum SaveOrLoadResult {
-	SL_OK     = 0, // completed successfully
-	SL_ERROR  = 1, // error that was caught before internal structures were modified
-	SL_REINIT = 2, // error that was caught in the middle of updating game state, need to clear it. (can only happen during load)
+	SL_OK     = 0, ///< completed successfully
+	SL_ERROR  = 1, ///< error that was caught before internal structures were modified
+	SL_REINIT = 2, ///< error that was caught in the middle of updating game state, need to clear it. (can only happen during load)
 };
 
 enum SaveOrLoadMode {
diff --git a/src/screenshot.cpp b/src/screenshot.cpp
index 7e2671c6d..3eebc1841 100644
--- a/src/screenshot.cpp
+++ b/src/screenshot.cpp
@@ -20,7 +20,7 @@ uint _num_screenshot_formats;
 uint _cur_screenshot_format;
 ScreenshotType current_screenshot_type;
 
-// called by the ScreenShot proc to generate screenshot lines.
+/* called by the ScreenShot proc to generate screenshot lines. */
 typedef void ScreenshotCallback(void *userdata, Pixel *buf, uint y, uint pitch, uint n);
 typedef bool ScreenshotHandlerProc(const char *name, ScreenshotCallback *callb, void *userdata, uint w, uint h, int pixelformat, const Colour *palette);
 
@@ -62,7 +62,7 @@ struct RgbQuad {
 };
 assert_compile(sizeof(RgbQuad) == 4);
 
-// generic .BMP writer
+/* generic .BMP writer */
 static bool MakeBmpImage(const char *name, ScreenshotCallback *callb, void *userdata, uint w, uint h, int pixelformat, const Colour *palette)
 {
 	BitmapFileHeader bfh;
@@ -72,23 +72,23 @@ static bool MakeBmpImage(const char *name, ScreenshotCallback *callb, void *user
 	uint i, padw;
 	uint n, maxlines;
 
-	// only implemented for 8bit images so far.
+	/* only implemented for 8bit images so far. */
 	if (pixelformat != 8)
 		return false;
 
 	f = fopen(name, "wb");
 	if (f == NULL) return false;
 
-	// each scanline must be aligned on a 32bit boundary
+	/* each scanline must be aligned on a 32bit boundary */
 	padw = ALIGN(w, 4);
 
-	// setup the file header
+	/* setup the file header */
 	bfh.type = TO_LE16('MB');
 	bfh.size = TO_LE32(sizeof(bfh) + sizeof(bih) + sizeof(RgbQuad) * 256 + padw * h);
 	bfh.reserved = 0;
 	bfh.off_bits = TO_LE32(sizeof(bfh) + sizeof(bih) + sizeof(RgbQuad) * 256);
 
-	// setup the info header
+	/* setup the info header */
 	bih.size = TO_LE32(sizeof(BitmapInfoHeader));
 	bih.width = TO_LE32(w);
 	bih.height = TO_LE32(h);
@@ -101,7 +101,7 @@ static bool MakeBmpImage(const char *name, ScreenshotCallback *callb, void *user
 	bih.clrused = 0;
 	bih.clrimp = 0;
 
-	// convert the palette to the windows format
+	/* convert the palette to the windows format */
 	for (i = 0; i != 256; i++) {
 		rq[i].red   = palette[i].r;
 		rq[i].green = palette[i].g;
@@ -109,15 +109,15 @@ static bool MakeBmpImage(const char *name, ScreenshotCallback *callb, void *user
 		rq[i].reserved = 0;
 	}
 
-	// write file header and info header and palette
+	/* write file header and info header and palette */
 	if (fwrite(&bfh, sizeof(bfh), 1, f) != 1) return false;
 	if (fwrite(&bih, sizeof(bih), 1, f) != 1) return false;
 	if (fwrite(rq, sizeof(rq), 1, f) != 1) return false;
 
-	// use by default 64k temp memory
+	/* use by default 64k temp memory */
 	maxlines = clamp(65536 / padw, 16, 128);
 
-	// now generate the bitmap bits
+	/* now generate the bitmap bits */
 	Pixel *buff = MallocT<Pixel>(padw * maxlines); // by default generate 128 lines at a time.
 	if (buff == NULL) {
 		fclose(f);
@@ -125,16 +125,16 @@ static bool MakeBmpImage(const char *name, ScreenshotCallback *callb, void *user
 	}
 	memset(buff, 0, padw * maxlines); // zero the buffer to have the padding bytes set to 0
 
-	// start at the bottom, since bitmaps are stored bottom up.
+	/* start at the bottom, since bitmaps are stored bottom up. */
 	do {
-		// determine # lines
+		/* determine # lines */
 		n = min(h, maxlines);
 		h -= n;
 
-		// render the pixels
+		/* render the pixels */
 		callb(userdata, buff, h, padw, n);
 
-		// write each line
+		/* write each line */
 		while (n)
 			if (fwrite(buff + (--n) * padw, padw, 1, f) != 1) {
 				free(buff);
@@ -175,7 +175,7 @@ static bool MakePNGImage(const char *name, ScreenshotCallback *callb, void *user
 	png_structp png_ptr;
 	png_infop info_ptr;
 
-	// only implemented for 8bit images so far.
+	/* only implemented for 8bit images so far. */
 	if (pixelformat != 8)
 		return false;
 
@@ -209,7 +209,7 @@ static bool MakePNGImage(const char *name, ScreenshotCallback *callb, void *user
 	png_set_IHDR(png_ptr, info_ptr, w, h, pixelformat, PNG_COLOR_TYPE_PALETTE,
 		PNG_INTERLACE_NONE, PNG_COMPRESSION_TYPE_DEFAULT, PNG_FILTER_TYPE_DEFAULT);
 
-	// convert the palette to the .PNG format.
+	/* convert the palette to the .PNG format. */
 	for (i = 0; i != 256; i++) {
 		rq[i].red   = palette[i].r;
 		rq[i].green = palette[i].g;
@@ -220,10 +220,10 @@ static bool MakePNGImage(const char *name, ScreenshotCallback *callb, void *user
 	png_write_info(png_ptr, info_ptr);
 	png_set_flush(png_ptr, 512);
 
-	// use by default 64k temp memory
+	/* use by default 64k temp memory */
 	maxlines = clamp(65536 / w, 16, 128);
 
-	// now generate the bitmap bits
+	/* now generate the bitmap bits */
 	Pixel *buff = MallocT<Pixel>(w * maxlines); // by default generate 128 lines at a time.
 	if (buff == NULL) {
 		png_destroy_write_struct(&png_ptr, &info_ptr);
@@ -234,14 +234,14 @@ static bool MakePNGImage(const char *name, ScreenshotCallback *callb, void *user
 
 	y = 0;
 	do {
-		// determine # lines to write
+		/* determine # lines to write */
 		n = min(h - y, maxlines);
 
-		// render the pixels into the buffer
+		/* render the pixels into the buffer */
 		callb(userdata, buff, y, w, n);
 		y += n;
 
-		// write them to png
+		/* write them to png */
 		for (i = 0; i != n; i++)
 			png_write_row(png_ptr, buff + i * w);
 	} while (y != h);
@@ -295,7 +295,7 @@ static bool MakePCXImage(const char *name, ScreenshotCallback *callb, void *user
 
 	memset(&pcx, 0, sizeof(pcx));
 
-	// setup pcx header
+	/* setup pcx header */
 	pcx.manufacturer = 10;
 	pcx.version = 5;
 	pcx.rle = 1;
@@ -310,16 +310,16 @@ static bool MakePCXImage(const char *name, ScreenshotCallback *callb, void *user
 	pcx.width = pcx.pitch = TO_LE16(w);
 	pcx.height = TO_LE16(h);
 
-	// write pcx header
+	/* write pcx header */
 	if (fwrite(&pcx, sizeof(pcx), 1, f) != 1) {
 		fclose(f);
 		return false;
 	}
 
-	// use by default 64k temp memory
+	/* use by default 64k temp memory */
 	maxlines = clamp(65536 / w, 16, 128);
 
-	// now generate the bitmap bits
+	/* now generate the bitmap bits */
 	Pixel *buff = MallocT<Pixel>(w * maxlines); // by default generate 128 lines at a time.
 	if (buff == NULL) {
 		fclose(f);
@@ -329,22 +329,22 @@ static bool MakePCXImage(const char *name, ScreenshotCallback *callb, void *user
 
 	y = 0;
 	do {
-		// determine # lines to write
+		/* determine # lines to write */
 		uint n = min(h - y, maxlines);
 		uint i;
 
-		// render the pixels into the buffer
+		/* render the pixels into the buffer */
 		callb(userdata, buff, y, w, n);
 		y += n;
 
-		// write them to pcx
+		/* write them to pcx */
 		for (i = 0; i != n; i++) {
 			const Pixel* bufp = buff + i * w;
 			byte runchar = bufp[0];
 			uint runcount = 1;
 			uint j;
 
-			// for each pixel...
+			/* for each pixel... */
 			for (j = 1; j < w; j++) {
 				Pixel ch = bufp[j];
 
@@ -366,7 +366,7 @@ static bool MakePCXImage(const char *name, ScreenshotCallback *callb, void *user
 				runcount++;
 			}
 
-			// write remaining bytes..
+			/* write remaining bytes.. */
 			if (runcount > 1 || (runchar & 0xC0) == 0xC0)
 				if (fputc(0xC0 | runcount, f) == EOF) {
 					free(buff);
@@ -383,7 +383,7 @@ static bool MakePCXImage(const char *name, ScreenshotCallback *callb, void *user
 
 	free(buff);
 
-	// write 8-bit color palette
+	/* write 8-bit color palette */
 	if (fputc(12, f) == EOF) {
 		fclose(f);
 		return false;
@@ -445,7 +445,7 @@ void SetScreenshotFormat(int i)
 	strcpy(_screenshot_format_name, _screenshot_formats[i].extension);
 }
 
-// screenshot generator that dumps the current video buffer
+/* screenshot generator that dumps the current video buffer */
 static void CurrentScreenCallback(void *userdata, Pixel *buf, uint y, uint pitch, uint n)
 {
 	for (; n > 0; --n) {
@@ -455,7 +455,7 @@ static void CurrentScreenCallback(void *userdata, Pixel *buf, uint y, uint pitch
 	}
 }
 
-// generate a large piece of the world
+/* generate a large piece of the world */
 static void LargeWorldCallback(void *userdata, Pixel *buf, uint y, uint pitch, uint n)
 {
 	ViewPort *vp = (ViewPort *)userdata;
diff --git a/src/screenshot.h b/src/screenshot.h
index be1e09e6e..308472625 100644
--- a/src/screenshot.h
+++ b/src/screenshot.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file screenshot.h */
+
 #ifndef SCREENSHOT_H
 #define SCREENSHOT_H
 
diff --git a/src/sdl.cpp b/src/sdl.cpp
index 3f70a8343..071a472af 100644
--- a/src/sdl.cpp
+++ b/src/sdl.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sdl.cpp */
+
 #include "stdafx.h"
 
 #ifdef WITH_SDL
diff --git a/src/sdl.h b/src/sdl.h
index 06549336d..d7f4658f9 100644
--- a/src/sdl.h
+++ b/src/sdl.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sdl.h */
+
 #ifndef SDL_H
 #define SDL_H
 
diff --git a/src/settings.cpp b/src/settings.cpp
index ed7e94b77..b8ae00572 100644
--- a/src/settings.cpp
+++ b/src/settings.cpp
@@ -1,6 +1,6 @@
 /* $Id$ */
 
-/** @file
+/** @file settings.cpp
  * All actions handling saving and loading of the settings/configuration goes on in this file.
  * The file consists of four parts:
  * <ol>
@@ -95,10 +95,10 @@ static void *pool_alloc(SettingsMemoryPool **pool, uint size)
 
 	size = ALIGN(size, sizeof(void*));
 
-	// first check if there's memory in the next pool
+	/* first check if there's memory in the next pool */
 	if (p->next && p->next->pos + size <= p->next->size) {
 		p = p->next;
-	// then check if there's not memory in the cur pool
+	/* then check if there's not memory in the cur pool */
 	} else if (p->pos + size > p->size) {
 		SettingsMemoryPool *n = pool_new(size);
 		*pool = n;
@@ -130,7 +130,7 @@ static void pool_free(SettingsMemoryPool **pool)
 	}
 }
 
-// structs describing the ini format.
+/** structs describing the ini format. */
 struct IniItem {
 	char *name;
 	char *value;
@@ -139,21 +139,21 @@ struct IniItem {
 };
 
 struct IniGroup {
-	char *name; // name of group
-	char *comment; //comment for group
+	char *name;        ///< name of group
+	char *comment;     ///<comment for group
 	IniItem *item, **last_item;
 	IniGroup *next;
 	IniFile *ini;
-	IniGroupType type; // type of group
+	IniGroupType type; ///< type of group
 };
 
 struct IniFile {
 	SettingsMemoryPool *pool;
 	IniGroup *group, **last_group;
-	char *comment; // last comment in file
+	char *comment;     ///< last comment in file
 };
 
-// allocate an inifile object
+/** allocate an inifile object */
 static IniFile *ini_alloc()
 {
 	IniFile *ini;
@@ -167,7 +167,7 @@ static IniFile *ini_alloc()
 	return ini;
 }
 
-// allocate an ini group object
+/** allocate an ini group object */
 static IniGroup *ini_group_alloc(IniFile *ini, const char *grpt, int len)
 {
 	IniGroup *grp = (IniGroup*)pool_alloc(&ini->pool, sizeof(IniGroup));
@@ -199,7 +199,7 @@ static IniItem *ini_item_alloc(IniGroup *group, const char *name, int len)
 	return item;
 }
 
-// load an ini file into the "abstract" format
+/** load an ini file into the "abstract" format */
 static IniFile *ini_load(const char *filename)
 {
 	char buffer[1024], c, *s, *t, *e;
@@ -217,23 +217,23 @@ static IniFile *ini_load(const char *filename)
 	in = fopen(filename, "r");
 	if (in == NULL) return ini;
 
-	// for each line in the file
+	/* for each line in the file */
 	while (fgets(buffer, sizeof(buffer), in)) {
 
-		// trim whitespace from the left side
+		/* trim whitespace from the left side */
 		for (s = buffer; *s == ' ' || *s == '\t'; s++);
 
-		// trim whitespace from right side.
+		/* trim whitespace from right side. */
 		e = s + strlen(s);
 		while (e > s && ((c=e[-1]) == '\n' || c == '\r' || c == ' ' || c == '\t')) e--;
 		*e = '\0';
 
-		// skip comments and empty lines
+		/* skip comments and empty lines */
 		if (*s == '#' || *s == ';' || *s == '\0') {
 			uint ns = comment_size + (e - s + 1);
 			uint a = comment_alloc;
 			uint pos;
-			// add to comment
+			/* add to comment */
 			if (ns > a) {
 				a = max(a, 128U);
 				do a*=2; while (a < ns);
@@ -246,7 +246,7 @@ static IniFile *ini_load(const char *filename)
 			continue;
 		}
 
-		// it's a group?
+		/* it's a group? */
 		if (s[0] == '[') {
 			if (e[-1] != ']') {
 				ShowInfoF("ini: invalid group name '%s'", buffer);
@@ -260,30 +260,30 @@ static IniFile *ini_load(const char *filename)
 				comment_size = 0;
 			}
 		} else if (group) {
-			// find end of keyname
+			/* find end of keyname */
 			for (t = s; *t != '\0' && *t != '=' && *t != '\t' && *t != ' '; t++);
 
-			// it's an item in an existing group
+			/* it's an item in an existing group */
 			item = ini_item_alloc(group, s, t-s);
 			if (comment_size) {
 				item->comment = (char*)pool_strdup(&ini->pool, comment, comment_size);
 				comment_size = 0;
 			}
 
-			// find start of parameter
+			/* find start of parameter */
 			while (*t == '=' || *t == ' ' || *t == '\t') t++;
 
 
-			// remove starting quotation marks
+			/* remove starting quotation marks */
 			if (*t == '\"') t++;
-			// remove ending quotation marks
+			/* remove ending quotation marks */
 			e = t + strlen(t);
 			if (e > t && e[-1] == '\"') e--;
 			*e = '\0';
 
 			item->value = (char*)pool_strdup(&ini->pool, t, e - t);
 		} else {
-			// it's an orphan item
+			/* it's an orphan item */
 			ShowInfoF("ini: '%s' outside of group", buffer);
 		}
 	}
@@ -299,25 +299,25 @@ static IniFile *ini_load(const char *filename)
 	return ini;
 }
 
-// lookup a group or make a new one
+/** lookup a group or make a new one */
 static IniGroup *ini_getgroup(IniFile *ini, const char *name, int len)
 {
 	IniGroup *group;
 
 	if (len == -1) len = strlen(name);
 
-	// does it exist already?
+	/* does it exist already? */
 	for (group = ini->group; group; group = group->next)
 		if (!memcmp(group->name, name, len) && group->name[len] == 0)
 			return group;
 
-	// otherwise make a new one
+	/* otherwise make a new one */
 	group = ini_group_alloc(ini, name, len);
 	group->comment = (char*)pool_strdup(&ini->pool, "\n", 1);
 	return group;
 }
 
-// lookup an item or make a new one
+/** lookup an item or make a new one */
 static IniItem *ini_getitem(IniGroup *group, const char *name, bool create)
 {
 	IniItem *item;
@@ -328,11 +328,11 @@ static IniItem *ini_getitem(IniGroup *group, const char *name, bool create)
 
 	if (!create) return NULL;
 
-	// otherwise make a new one
+	/* otherwise make a new one */
 	return ini_item_alloc(group, name, len);
 }
 
-// save ini file from the "abstract" format.
+/** save ini file from the "abstract" format. */
 static bool ini_save(const char *filename, IniFile *ini)
 {
 	FILE *f;
@@ -380,13 +380,13 @@ static int lookup_oneofmany(const char *many, const char *one, int onelen)
 
 	if (onelen == -1) onelen = strlen(one);
 
-	// check if it's an integer
+	/* check if it's an integer */
 	if (*one >= '0' && *one <= '9')
 		return strtoul(one, NULL, 0);
 
 	idx = 0;
 	for (;;) {
-		// find end of item
+		/* find end of item */
 		s = many;
 		while (*s != '|' && *s != 0) s++;
 		if (s - many == onelen && !memcmp(one, many, onelen)) return idx;
@@ -408,7 +408,7 @@ static uint32 lookup_manyofmany(const char *many, const char *str)
 	uint32 res = 0;
 
 	for (;;) {
-		// skip "whitespace"
+		/* skip "whitespace" */
 		while (*str == ' ' || *str == '\t' || *str == '|') str++;
 		if (*str == 0) break;
 
@@ -522,7 +522,7 @@ static void make_oneofmany(char *buf, const char *many, int id)
 {
 	int orig_id = id;
 
-	// Look for the id'th element
+	/* Look for the id'th element */
 	while (--id >= 0) {
 		for (; *many != '|'; many++) {
 			if (*many == '\0') { // not found
@@ -533,7 +533,7 @@ static void make_oneofmany(char *buf, const char *many, int id)
 		many++; // pass the |-character
 	}
 
-	// copy string until next item (|) or the end of the list if this is the last one
+	/* copy string until next item (|) or the end of the list if this is the last one */
 	while (*many != '\0' && *many != '|') *buf++ = *many++;
 	*buf = '\0';
 }
@@ -685,7 +685,7 @@ static void ini_load_settings(IniFile *ini, const SettingDesc *sd, const char *g
 
 		if (!SlIsObjectCurrentlyValid(sld->version_from, sld->version_to)) continue;
 
-		// XXX - wtf is this?? (group override?)
+		/* XXX - wtf is this?? (group override?) */
 		s = strchr(sdb->name, '.');
 		if (s != NULL) {
 			group = ini_getgroup(ini, sdb->name, s - sdb->name);
@@ -761,7 +761,7 @@ static void ini_save_settings(IniFile *ini, const SettingDesc *sd, const char *g
 		if (!SlIsObjectCurrentlyValid(sld->version_from, sld->version_to)) continue;
 		if (sld->conv & SLF_CONFIG_NO) continue;
 
-		// XXX - wtf is this?? (group override?)
+		/* XXX - wtf is this?? (group override?) */
 		s = strchr(sdb->name, '.');
 		if (s != NULL) {
 			group = ini_getgroup(ini, sdb->name, s - sdb->name);
@@ -776,7 +776,7 @@ static void ini_save_settings(IniFile *ini, const SettingDesc *sd, const char *g
 		ptr = GetVariableAddress(object, sld);
 
 		if (item->value != NULL) {
-			// check if the value is the same as the old value
+			/* check if the value is the same as the old value */
 			const void *p = string_to_val(sdb, item->value);
 
 			/* The main type of a variable/setting is in bytes 8-15
@@ -1069,7 +1069,7 @@ static void ini_save_setting_list(IniFile *ini, const char *grpname, char **list
 #include "gui.h"
 #include "town.h"
 #include "gfx.h"
-// virtual PositionMainToolbar function, calls the right one.
+/* virtual PositionMainToolbar function, calls the right one.*/
 static int32 v_PositionMainToolbar(int32 p1)
 {
 	if (_game_mode != GM_MENU) PositionMainToolbar(NULL);
@@ -1460,7 +1460,7 @@ const SettingDesc _patch_settings[] = {
 	SDT_CONDVAR (Patches, npf_road_drive_through_penalty, SLE_UINT, 47, SL_MAX_VERSION, 0, 0,  8 * NPF_TILE_LENGTH, 0, 1000000, 0, STR_NULL, NULL),
 
 
-	// The maximum number of nodes to search
+	/* The maximum number of nodes to search */
 	SDT_CONDBOOL(Patches, yapf.disable_node_optimization  ,           28, SL_MAX_VERSION, 0, 0, false                   ,                       STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.max_search_nodes           , SLE_UINT, 28, SL_MAX_VERSION, 0, 0, 10000                   ,      500, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDBOOL(Patches, yapf.rail_firstred_twoway_eol   ,           28, SL_MAX_VERSION, 0, 0,  true                   ,                       STR_NULL, NULL),
@@ -1472,22 +1472,22 @@ const SettingDesc _patch_settings[] = {
 	SDT_CONDVAR (Patches, yapf.rail_slope_penalty         , SLE_UINT, 28, SL_MAX_VERSION, 0, 0,     2 * YAPF_TILE_LENGTH,        0, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_curve45_penalty       , SLE_UINT, 28, SL_MAX_VERSION, 0, 0,     1 * YAPF_TILE_LENGTH,        0, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_curve90_penalty       , SLE_UINT, 28, SL_MAX_VERSION, 0, 0,     6 * YAPF_TILE_LENGTH,        0, 1000000, 0, STR_NULL, NULL),
-	// This penalty is applied when a train reverses inside a depot
+	/* This penalty is applied when a train reverses inside a depot */
 	SDT_CONDVAR (Patches, yapf.rail_depot_reverse_penalty , SLE_UINT, 28, SL_MAX_VERSION, 0, 0,    50 * YAPF_TILE_LENGTH,        0, 1000000, 0, STR_NULL, NULL),
-	// This is the penalty for level crossings (for trains only)
+	/* This is the penalty for level crossings (for trains only) */
 	SDT_CONDVAR (Patches, yapf.rail_crossing_penalty      , SLE_UINT, 28, SL_MAX_VERSION, 0, 0,     3 * YAPF_TILE_LENGTH,        0, 1000000, 0, STR_NULL, NULL),
-	// look-ahead how many signals are checked
+	/* look-ahead how many signals are checked */
 	SDT_CONDVAR (Patches, yapf.rail_look_ahead_max_signals, SLE_UINT, 28, SL_MAX_VERSION, 0, 0,    10                   ,        1,     100, 0, STR_NULL, NULL),
-	// look-ahead n-th red signal penalty polynomial: penalty = p2 * n^2 + p1 * n + p0
+	/* look-ahead n-th red signal penalty polynomial: penalty = p2 * n^2 + p1 * n + p0 */
 	SDT_CONDVAR (Patches, yapf.rail_look_ahead_signal_p0  , SLE_INT , 28, SL_MAX_VERSION, 0, 0,   500                   , -1000000, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_look_ahead_signal_p1  , SLE_INT , 28, SL_MAX_VERSION, 0, 0,  -100                   , -1000000, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_look_ahead_signal_p2  , SLE_INT , 28, SL_MAX_VERSION, 0, 0,     5                   , -1000000, 1000000, 0, STR_NULL, NULL),
-	// penalties for too long or too short station platforms
+	/* penalties for too long or too short station platforms */
 	SDT_CONDVAR (Patches, yapf.rail_longer_platform_penalty,           SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  8 * YAPF_TILE_LENGTH, 0,   20000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_longer_platform_per_tile_penalty,  SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  0 * YAPF_TILE_LENGTH, 0,   20000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_shorter_platform_penalty,          SLE_UINT, 33, SL_MAX_VERSION, 0, 0, 40 * YAPF_TILE_LENGTH, 0,   20000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.rail_shorter_platform_per_tile_penalty, SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  0 * YAPF_TILE_LENGTH, 0,   20000, 0, STR_NULL, NULL),
-	// road vehicles - penalties
+	/* road vehicles - penalties */
 	SDT_CONDVAR (Patches, yapf.road_slope_penalty                    , SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  2 * YAPF_TILE_LENGTH, 0, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.road_curve_penalty                    , SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  1 * YAPF_TILE_LENGTH, 0, 1000000, 0, STR_NULL, NULL),
 	SDT_CONDVAR (Patches, yapf.road_crossing_penalty                 , SLE_UINT, 33, SL_MAX_VERSION, 0, 0,  3 * YAPF_TILE_LENGTH, 0, 1000000, 0, STR_NULL, NULL),
diff --git a/src/settings.h b/src/settings.h
index 142f4136a..726b72483 100644
--- a/src/settings.h
+++ b/src/settings.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file settings.h */
+
 #ifndef SETTINGS_H
 #define SETTINGS_H
 
@@ -12,12 +14,12 @@
 enum SettingDescTypeLong {
 	/* 4 bytes allocated a maximum of 16 types for GenericType */
 	SDT_BEGIN       = 0,
-	SDT_NUMX        = 0, // any number-type
-	SDT_BOOLX       = 1, // a boolean number
-	SDT_ONEOFMANY   = 2, // bitmasked number where only ONE bit may be set
-	SDT_MANYOFMANY  = 3, // bitmasked number where MULTIPLE bits may be set
-	SDT_INTLIST     = 4, // list of integers seperated by a comma ','
-	SDT_STRING      = 5, // string with a pre-allocated buffer
+	SDT_NUMX        = 0, ///< any number-type
+	SDT_BOOLX       = 1, ///< a boolean number
+	SDT_ONEOFMANY   = 2, ///< bitmasked number where only ONE bit may be set
+	SDT_MANYOFMANY  = 3, ///< bitmasked number where MULTIPLE bits may be set
+	SDT_INTLIST     = 4, ///< list of integers seperated by a comma ','
+	SDT_STRING      = 5, ///< string with a pre-allocated buffer
 	SDT_END,
 	/* 10 more possible primitives */
 };
diff --git a/src/settings_gui.cpp b/src/settings_gui.cpp
index bfe3d54f9..0f601a19f 100644
--- a/src/settings_gui.cpp
+++ b/src/settings_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file settings_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "currency.h"
@@ -352,9 +354,9 @@ static inline bool GetBitAndShift(uint32 *b)
  */
 static const int16 _default_game_diff[3][GAME_DIFFICULTY_NUM] = { /*
 	 A, B, C, D,   E, F, G, H, I, J, K, L, M, N, O, P, Q, R*/
-	{2, 2, 1, 3, 300, 2, 0, 2, 0, 1, 2, 0, 1, 0, 0, 0, 0, 0}, //easy
-	{4, 1, 1, 2, 150, 3, 1, 3, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1}, //medium
-	{7, 0, 2, 2, 100, 4, 1, 3, 2, 2, 0, 2, 3, 2, 1, 1, 1, 2}, //hard
+	{2, 2, 1, 3, 300, 2, 0, 2, 0, 1, 2, 0, 1, 0, 0, 0, 0, 0}, ///< easy
+	{4, 1, 1, 2, 150, 3, 1, 3, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1}, ///< medium
+	{7, 0, 2, 2, 100, 4, 1, 3, 2, 2, 0, 2, 3, 2, 1, 1, 1, 2}, ///< hard
 };
 
 void SetDifficultyLevel(int mode, GameOptions *gm_opt)
@@ -393,7 +395,7 @@ enum {
 	GAMEDIFF_WND_ROWSIZE    = 9
 };
 
-// Temporary holding place of values in the difficulty window until 'Save' is clicked
+/* Temporary holding place of values in the difficulty window until 'Save' is clicked */
 static GameOptions _opt_mod_temp;
 // 0x383E = (1 << 13) | (1 << 12) | (1 << 11) | (1 << 5) | (1 << 4) | (1 << 3) | (1 << 2) | (1 << 1)
 #define DIFF_INGAME_DISABLED_BUTTONS 0x383E
@@ -457,7 +459,7 @@ static void GameDifficultyWndProc(Window *w, WindowEvent *e)
 			uint btn, dis;
 			int16 val;
 
-			// Don't allow clients to make any changes
+			/* Don't allow clients to make any changes */
 			if  (_networking && !_network_server)
 				return;
 
@@ -469,12 +471,12 @@ static void GameDifficultyWndProc(Window *w, WindowEvent *e)
 			if (y < 0)
 				return;
 
-			// Get button from Y coord.
+			/* Get button from Y coord. */
 			btn = y / (GAMEDIFF_WND_ROWSIZE + 2);
 			if (btn >= GAME_DIFFICULTY_NUM || y % (GAMEDIFF_WND_ROWSIZE + 2) >= 9)
 				return;
 
-			// Clicked disabled button?
+			/* Clicked disabled button? */
 			dis = (_game_mode == GM_NORMAL) ? DIFF_INGAME_DISABLED_BUTTONS : 0;
 
 			if (HASBIT(dis, btn))
diff --git a/src/ship.h b/src/ship.h
index e4bfd9f98..4a9ce9190 100644
--- a/src/ship.h
+++ b/src/ship.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ship.h */
+
 #ifndef SHIP_H
 #define SHIP_H
 
diff --git a/src/ship_cmd.cpp b/src/ship_cmd.cpp
index cf6687998..9bc935e04 100644
--- a/src/ship_cmd.cpp
+++ b/src/ship_cmd.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ship_cmd.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "ship.h"
@@ -62,8 +64,8 @@ void DrawShipEngine(int x, int y, EngineID engine, SpriteID pal)
 
 /** Get the size of the sprite of a ship sprite heading west (used for lists)
  * @param engine The engine to get the sprite from
- * @param &width The width of the sprite
- * @param &height The height of the sprite
+ * @param width The width of the sprite
+ * @param height The height of the sprite
  */
 void GetShipSpriteSize(EngineID engine, uint &width, uint &height)
 {
@@ -191,7 +193,7 @@ void OnNewDay_Ship(Vehicle *v)
 	SubtractMoneyFromPlayerFract(v->owner, cost);
 
 	InvalidateWindow(WC_VEHICLE_DETAILS, v->index);
-	//we need this for the profit
+	/* we need this for the profit */
 	InvalidateWindowClasses(WC_SHIPS_LIST);
 }
 
@@ -376,10 +378,10 @@ static void CheckShipLeaveDepot(Vehicle *v)
 	tile = v->tile;
 	axis = GetShipDepotAxis(tile);
 
-	// Check first side
+	/* Check first side */
 	if (_ship_sometracks[axis] & GetTileShipTrackStatus(TILE_ADD(tile, ToTileIndexDiff(_ship_leave_depot_offs[axis])))) {
 		m = (axis == AXIS_X) ? 0x101 : 0x207;
-	// Check second side
+	/* Check second side */
 	} else if (_ship_sometracks[axis + 2] & GetTileShipTrackStatus(TILE_ADD(tile, -2 * ToTileIndexDiff(_ship_leave_depot_offs[axis])))) {
 		m = (axis == AXIS_X) ? 0x105 : 0x203;
 	} else {
@@ -405,14 +407,14 @@ static bool ShipAccelerate(Vehicle *v)
 
 	spd = min(v->cur_speed + 1, v->max_speed);
 
-	//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)
 			InvalidateWindowWidget(WC_VEHICLE_VIEW, v->index, STATUS_BAR);
 	}
 
-	// Decrease somewhat when turning
+	/* Decrease somewhat when turning */
 	if (!(v->direction & 1)) spd = spd * 3 / 4;
 
 	if (spd == 0) return false;
@@ -455,7 +457,7 @@ struct PathFindShip {
 
 static bool ShipTrackFollower(TileIndex tile, PathFindShip *pfs, int track, uint length, byte *state)
 {
-	// Found dest?
+	/* Found dest? */
 	if (tile == pfs->dest_coords) {
 		pfs->best_bird_dist = 0;
 
@@ -463,7 +465,7 @@ static bool ShipTrackFollower(TileIndex tile, PathFindShip *pfs, int track, uint
 		return true;
 	}
 
-	// Skip this tile in the calculation
+	/* Skip this tile in the calculation */
 	if (tile != pfs->skiptile) {
 		pfs->best_bird_dist = minu(pfs->best_bird_dist, DistanceMaxPlusManhattan(pfs->dest_coords, tile));
 	}
@@ -543,7 +545,7 @@ static inline NPFFoundTargetData PerfNPFRouteToStationOrTile(TileIndex tile, Tra
 	return ret;
 }
 
-/* returns the track to choose on the next tile, or -1 when it's better to
+/** returns the track to choose on the next tile, or -1 when it's better to
  * reverse. The tile given is the tile we are about to enter, enterdir is the
  * direction in which we are entering the tile */
 static Track ChooseShipTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks)
@@ -558,7 +560,7 @@ static Track ChooseShipTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir,
 		NPFFoundTargetData ftd;
 		TileIndex src_tile = TILE_ADD(tile, TileOffsByDiagDir(ReverseDiagDir(enterdir)));
 		Trackdir trackdir = GetVehicleTrackdir(v);
-		assert(trackdir != INVALID_TRACKDIR); /* Check that we are not in a depot */
+		assert(trackdir != INVALID_TRACKDIR); // Check that we are not in a depot
 
 		NPFFillWithOrderData(&fstd, v);
 
@@ -731,7 +733,7 @@ static void ShipController(Vehicle *v)
 
 							/* Process station in the orderlist. */
 							st = GetStation(v->current_order.dest);
-							if (st->facilities & FACIL_DOCK) { /* ugly, ugly workaround for problem with ships able to drop off cargo at wrong stations */
+							if (st->facilities & FACIL_DOCK) { // ugly, ugly workaround for problem with ships able to drop off cargo at wrong stations
 								v->BeginLoading();
 								v->current_order.flags &= OF_FULL_LOAD | OF_UNLOAD | OF_TRANSFER;
 								v->current_order.flags |= OF_NON_STOP;
@@ -743,7 +745,7 @@ static void ShipController(Vehicle *v)
 									MarkShipDirty(v);
 								}
 								InvalidateWindowWidget(WC_VEHICLE_VIEW, v->index, STATUS_BAR);
-							} else { /* leave stations without docks right aways */
+							} else { // leave stations without docks right aways
 								v->current_order.type = OT_LEAVESTATION;
 								v->cur_order_index++;
 								InvalidateVehicleOrder(v);
@@ -834,6 +836,7 @@ void ShipsYearlyLoop()
 
 /** Build a ship.
  * @param tile tile of depot where ship is built
+ * @param flags type of operation
  * @param p1 ship type being built (engine)
  * @param p2 bit 0 when set, the unitnumber will be 0, otherwise it will be a free number
  */
@@ -930,6 +933,7 @@ int32 CmdBuildShip(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Sell a ship.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 vehicle ID to be sold
  * @param p2 unused
  */
@@ -963,6 +967,7 @@ int32 CmdSellShip(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Start/Stop a ship.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 ship ID to start/stop
  * @param p2 unused
  */
@@ -1001,6 +1006,7 @@ int32 CmdStartStopShip(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Send a ship to the depot.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 vehicle ID to send to the depot
  * @param p2 various bitmasked elements
  * - p2 bit 0-3 - DEPOT_ flags (see vehicle.h)
@@ -1073,6 +1079,7 @@ int32 CmdSendShipToDepot(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Refits a ship to the specified cargo type.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 vehicle ID of the ship to refit
  * @param p2 various bitstuffed elements
  * - p2 = (bit 0-7) - the new cargo type to refit to (p2 & 0xFF)
diff --git a/src/ship_gui.cpp b/src/ship_gui.cpp
index 6d656630f..48a645016 100644
--- a/src/ship_gui.cpp
+++ b/src/ship_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file ship_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -32,7 +34,7 @@ static void ShipDetailsWndProc(Window *w, WindowEvent *e)
 		StringID str;
 
 		SetWindowWidgetDisabledState(w, 2, v->owner != _local_player);
-		// disable service-scroller when interval is set to disabled
+		/* disable service-scroller when interval is set to disabled */
 		SetWindowWidgetDisabledState(w, 5, !_patches.servint_ships);
 		SetWindowWidgetDisabledState(w, 6, !_patches.servint_ships);
 
diff --git a/src/signs.cpp b/src/signs.cpp
index df0494374..4e394ea77 100644
--- a/src/signs.cpp
+++ b/src/signs.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file signs.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
@@ -30,6 +32,7 @@ DEFINE_OLD_POOL(Sign, Sign, SignPoolNewBlock, NULL)
 /**
  *
  * Update the coordinate of one sign
+ * @param si Pointer to the Sign
  *
  */
 static void UpdateSignVirtCoords(Sign *si)
@@ -97,6 +100,10 @@ static Sign *AllocateSign()
 	return NULL;
 }
 
+/**
+ * Destroy a sign placed on the map
+ * @param si Pointer to the Sign to remove
+ */
 void DestroySign(Sign *si)
 {
 	DeleteName(si->str);
@@ -107,6 +114,7 @@ void DestroySign(Sign *si)
  * no effect whatsoever except for the colour the sign gets for easy recognition,
  * but everybody is able to rename/remove it.
  * @param tile tile to place sign at
+ * @param flags type of operation
  * @param p1 unused
  * @param p2 unused
  */
@@ -142,8 +150,10 @@ int32 CmdPlaceSign(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
  * the user wanted to delete it. So delete it. Ownership of signs
  * has no meaning/effect whatsoever except for eyecandy
  * @param tile unused
+ * @param flags type of operation
  * @param p1 index of the sign to be renamed/removed
  * @param p2 unused
+ * @return 0 if succesfull, otherwise CMD_ERROR
  */
 int32 CmdRenameSign(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -175,7 +185,7 @@ int32 CmdRenameSign(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			/* Free the name, because we did not assign it yet */
 			DeleteName(str);
 		}
-	} else { /* Delete sign */
+	} else { // Delete sign
 		if (flags & DC_EXEC) {
 			Sign *si = GetSign(p1);
 
@@ -191,9 +201,11 @@ int32 CmdRenameSign(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 }
 
 /**
- *
  * Callback function that is called after a sign is placed
- *
+ * @param success of the operation
+ * @param tile unused
+ * @param p1 unused
+ * @param p2 unused
  */
 void CcPlaceSign(bool success, TileIndex tile, uint32 p1, uint32 p2)
 {
@@ -207,7 +219,7 @@ void CcPlaceSign(bool success, TileIndex tile, uint32 p1, uint32 p2)
  *
  * PlaceProc function, called when someone pressed the button if the
  *  sign-tool is selected
- *
+ * @param tile on which to place the sign
  */
 void PlaceProc_Sign(TileIndex tile)
 {
diff --git a/src/signs.h b/src/signs.h
index 1a897594b..49ccefedc 100644
--- a/src/signs.h
+++ b/src/signs.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file signs.h */
+
 #ifndef SIGNS_H
 #define SIGNS_H
 
@@ -62,7 +64,7 @@ VARDEF bool _sign_sort_dirty;
 void UpdateAllSignVirtCoords();
 void PlaceProc_Sign(TileIndex tile);
 
-/* misc.c */
+/* misc.cpp */
 void ShowRenameSignWindow(const Sign *si);
 
 void ShowSignList();
diff --git a/src/signs_gui.cpp b/src/signs_gui.cpp
index 754500700..270bed1bc 100644
--- a/src/signs_gui.cpp
+++ b/src/signs_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file signs_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
diff --git a/src/slope.h b/src/slope.h
index bd5958af8..13f106ee1 100644
--- a/src/slope.h
+++ b/src/slope.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file slope.h */
+
 #ifndef SLOPE_H
 #define SLOPE_H
 
diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp
index 06591b0e9..b2b546060 100644
--- a/src/smallmap_gui.cpp
+++ b/src/smallmap_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file smallmap_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -332,13 +334,13 @@ static void DrawSmallMapStuff(Pixel *dst, uint xc, uint yc, int pitch, int reps,
 	Pixel *dst_ptr_end = _screen.dst_ptr + _screen.width * _screen.height - _screen.width;
 
 	do {
-		// check if the tile (xc,yc) is within the map range
+		/* check if the tile (xc,yc) is within the map range */
 		if (xc < MapMaxX() && yc < MapMaxY()) {
-			// check if the dst pointer points to a pixel inside the screen buffer
+			/* check if the dst pointer points to a pixel inside the screen buffer */
 			if (dst > _screen.dst_ptr && dst < dst_ptr_end)
 				WRITE_PIXELS_OR(dst, proc(TileXY(xc, yc)) & mask);
 		}
-	// switch to next tile in the column
+	/* switch to next tile in the column */
 	} while (xc++, yc++, dst += pitch, --reps != 0);
 }
 
@@ -454,7 +456,7 @@ static inline uint32 GetSmallMapRoutesPixels(TileIndex tile)
 			default:              bits = MKCOLOR(0xFFFFFFFF); break;
 		}
 	} else {
-		// ground color
+		/* ground color */
 		bits = ApplyMask(MKCOLOR(0x54545454), &_smallmap_contours_andor[t]);
 	}
 	return bits;
@@ -693,7 +695,7 @@ skip_column:
 		FOR_ALL_VEHICLES(v) {
 			if (v->type != VEH_SPECIAL &&
 					(v->vehstatus & (VS_HIDDEN | VS_UNCLICKABLE)) == 0) {
-				// Remap into flat coordinates.
+				/* Remap into flat coordinates. */
 				Point pt = RemapCoords(
 					v->x_pos / TILE_SIZE - WP(w,smallmap_d).scroll_x / TILE_SIZE, // divide each one separately because (a-b)/c != a/c-b/c in integer world
 					v->y_pos / TILE_SIZE - WP(w,smallmap_d).scroll_y / TILE_SIZE, //    dtto
@@ -701,32 +703,32 @@ skip_column:
 				x = pt.x;
 				y = pt.y;
 
-				// Check if y is out of bounds?
+				/* Check if y is out of bounds? */
 				y -= dpi->top;
 				if (!IS_INT_INSIDE(y, 0, dpi->height)) continue;
 
-				// Default is to draw both pixels.
+				/* Default is to draw both pixels. */
 				skip = false;
 
-				// Offset X coordinate
+				/* Offset X coordinate */
 				x -= WP(w,smallmap_d).subscroll + 3 + dpi->left;
 
 				if (x < 0) {
-					// if x+1 is 0, that means we're on the very left edge,
-					//  and should thus only draw a single pixel
+					/* if x+1 is 0, that means we're on the very left edge,
+					 *  and should thus only draw a single pixel */
 					if (++x != 0) continue;
 					skip = true;
 				} else if (x >= dpi->width - 1) {
-					// Check if we're at the very right edge, and if so draw only a single pixel
+					/* Check if we're at the very right edge, and if so draw only a single pixel */
 					if (x != dpi->width - 1) continue;
 					skip = true;
 				}
 
-				// Calculate pointer to pixel and the color
+				/* Calculate pointer to pixel and the color */
 				ptr = dpi->dst_ptr + y * dpi->pitch + x;
 				color = (type == 1) ? _vehicle_type_colors[v->type] : 0xF;
 
-				// And draw either one or two pixels depending on clipping
+				/* And draw either one or two pixels depending on clipping */
 				ptr[0] = color;
 				if (!skip) ptr[1] = color;
 			}
@@ -737,7 +739,7 @@ skip_column:
 		const Town *t;
 
 		FOR_ALL_TOWNS(t) {
-			// Remap the town coordinate
+			/* Remap the town coordinate */
 			Point pt = RemapCoords(
 				(int)(TileX(t->xy) * TILE_SIZE - WP(w, smallmap_d).scroll_x) / TILE_SIZE,
 				(int)(TileY(t->xy) * TILE_SIZE - WP(w, smallmap_d).scroll_y) / TILE_SIZE,
@@ -745,23 +747,23 @@ skip_column:
 			x = pt.x - WP(w,smallmap_d).subscroll + 3 - (t->sign.width_2 >> 1);
 			y = pt.y;
 
-			// Check if the town sign is within bounds
+			/* Check if the town sign is within bounds */
 			if (x + t->sign.width_2 > dpi->left &&
 					x < dpi->left + dpi->width &&
 					y + 6 > dpi->top &&
 					y < dpi->top + dpi->height) {
-				// And draw it.
+				/* And draw it. */
 				SetDParam(0, t->index);
 				DrawString(x, y, STR_2056, 12);
 			}
 		}
 	}
 
-	// Draw map indicators
+	/* Draw map indicators */
 	{
 		Point pt;
 
-		// Find main viewport.
+		/* Find main viewport. */
 		vp = FindWindowById(WC_MAIN_WINDOW,0)->viewport;
 
 		pt = RemapCoords(WP(w, smallmap_d).scroll_x, WP(w, smallmap_d).scroll_y, 0);
@@ -1033,7 +1035,7 @@ static void ExtraViewPortWndProc(Window *w, WindowEvent *e)
 			int x = WP(w, vp_d).scrollpos_x; // Where is the main looking at
 			int y = WP(w, vp_d).scrollpos_y;
 
-			// set this view to same location. Based on the center, adjusting for zoom
+			/* set this view to same location. Based on the center, adjusting for zoom */
 			WP(w2, vp_d).scrollpos_x =  x - (w2->viewport->virtual_width -  w->viewport->virtual_width) / 2;
 			WP(w2, vp_d).scrollpos_y =  y - (w2->viewport->virtual_height - w->viewport->virtual_height) / 2;
 		} break;
@@ -1094,18 +1096,18 @@ void ShowExtraViewPortWindow()
 	Window *w, *v;
 	int i = 0;
 
-	// find next free window number for extra viewport
+	/* find next free window number for extra viewport */
 	while (FindWindowById(WC_EXTRA_VIEW_PORT, i) != NULL) i++;
 
 	w = AllocateWindowDescFront(&_extra_view_port_desc, i);
 	if (w != NULL) {
 		int x, y;
-		// the main window with the main view
+		/* the main window with the main view */
 		v = FindWindowById(WC_MAIN_WINDOW, 0);
-		// New viewport start ats (zero,zero)
+		/* New viewport start ats (zero,zero) */
 		AssignWindowViewport(w, 3, 17, 294, 214, 0 , 0);
 
-		// center on same place as main window (zoom is maximum, no adjustment needed)
+		/* center on same place as main window (zoom is maximum, no adjustment needed) */
 		x = WP(v, vp_d).scrollpos_x;
 		y = WP(v, vp_d).scrollpos_y;
 		WP(w, vp_d).scrollpos_x = x + (v->viewport->virtual_width  - (294)) / 2;
diff --git a/src/sound.cpp b/src/sound.cpp
index c74927c1a..3dea2e5a2 100644
--- a/src/sound.cpp
+++ b/src/sound.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sound.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -51,12 +53,12 @@ static void OpenBankFile(const char *filename)
 
 		FioSeekTo(fe->file_offset, SEEK_SET);
 
-		// Check for special case, see else case
+		/* Check for special case, see else case */
 		FioReadBlock(name, FioReadByte()); // Read the name of the sound
 		if (strcmp(name, "Corrupt sound") != 0) {
 			FioSeekTo(12, SEEK_CUR); // Skip past RIFF header
 
-			// Read riff tags
+			/* Read riff tags */
 			for (;;) {
 				uint32 tag = FioReadDword();
 				uint32 size = FioReadDword();
@@ -130,7 +132,7 @@ bool SoundInitialize(const char *filename)
 	return true;
 }
 
-// Low level sound player
+/* Low level sound player */
 static void StartSound(uint sound, int panning, uint volume)
 {
 	MixerChannel *mc;
diff --git a/src/sound.h b/src/sound.h
index 5826ab19f..ff5c130d9 100644
--- a/src/sound.h
+++ b/src/sound.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sound.h */
+
 #ifndef SOUND_H
 #define SOUND_H
 
diff --git a/src/sprite.h b/src/sprite.h
index 91b108d34..6c6c8e85f 100644
--- a/src/sprite.h
+++ b/src/sprite.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file sprite.h */
+
 #ifndef SPRITE_H
 #define SPRITE_H
 
@@ -40,7 +42,7 @@ struct DrawBuildingsTileStruct {
 	byte draw_proc;  /* this allows to specify a special drawing procedure.*/
 };
 
-// Iterate through all DrawTileSeqStructs in DrawTileSprites.
+/** Iterate through all DrawTileSeqStructs in DrawTileSprites. */
 #define foreach_draw_tile_seq(idx, list) for (idx = list; ((byte) idx->delta_x) != 0x80; idx++)
 
 
diff --git a/src/spritecache.cpp b/src/spritecache.cpp
index c06d7aa9e..596f31658 100644
--- a/src/spritecache.cpp
+++ b/src/spritecache.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file spritechache.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -237,7 +239,7 @@ static uint32 GetSpriteCacheUsage()
 
 void IncreaseSpriteLRU()
 {
-	// Increase all LRU values
+	/* Increase all LRU values */
 	if (_sprite_lru_counter > 16384) {
 		SpriteID i;
 
@@ -256,15 +258,15 @@ void IncreaseSpriteLRU()
 		_sprite_lru_counter = 0;
 	}
 
-	// Compact sprite cache every now and then.
+	/* Compact sprite cache every now and then. */
 	if (++_compact_cache_counter >= 740) {
 		CompactSpriteCache();
 		_compact_cache_counter = 0;
 	}
 }
 
-// Called when holes in the sprite cache should be removed.
-// That is accomplished by moving the cached data.
+/** Called when holes in the sprite cache should be removed.
+ * That is accomplished by moving the cached data. */
 static void CompactSpriteCache()
 {
 	MemBlock *s;
@@ -277,26 +279,26 @@ static void CompactSpriteCache()
 			MemBlock temp;
 			SpriteID i;
 
-			// Since free blocks are automatically coalesced, this should hold true.
+			/* Since free blocks are automatically coalesced, this should hold true. */
 			assert(!(next->size & S_FREE_MASK));
 
-			// If the next block is the sentinel block, we can safely return
+			/* If the next block is the sentinel block, we can safely return */
 			if (next->size == 0)
 				break;
 
-			// Locate the sprite belonging to the next pointer.
+			/* Locate the sprite belonging to the next pointer. */
 			for (i = 0; GetSpriteCache(i)->ptr != next->data; i++) {
 				assert(i != _spritecache_items);
 			}
 
 			GetSpriteCache(i)->ptr = s->data; // Adjust sprite array entry
-			// Swap this and the next block
+			/* Swap this and the next block */
 			temp = *s;
 			memmove(s, next, next->size);
 			s = NextBlock(s);
 			*s = temp;
 
-			// Coalesce free blocks
+			/* Coalesce free blocks */
 			while (NextBlock(s)->size & S_FREE_MASK) {
 				s->size += NextBlock(s)->size & ~S_FREE_MASK;
 			}
@@ -324,18 +326,18 @@ static void DeleteEntryFromSpriteCache()
 		}
 	}
 
-	// Display an error message and die, in case we found no sprite at all.
-	// This shouldn't really happen, unless all sprites are locked.
+	/* Display an error message and die, in case we found no sprite at all.
+	 * This shouldn't really happen, unless all sprites are locked. */
 	if (best == (uint)-1)
 		error("Out of sprite memory");
 
-	// Mark the block as free (the block must be in use)
+	/* Mark the block as free (the block must be in use) */
 	s = (MemBlock*)GetSpriteCache(best)->ptr - 1;
 	assert(!(s->size & S_FREE_MASK));
 	s->size |= S_FREE_MASK;
 	GetSpriteCache(best)->ptr = NULL;
 
-	// And coalesce adjacent free blocks
+	/* And coalesce adjacent free blocks */
 	for (s = _spritecache_ptr; s->size != 0; s = NextBlock(s)) {
 		if (s->size & S_FREE_MASK) {
 			while (NextBlock(s)->size & S_FREE_MASK) {
@@ -364,10 +366,10 @@ static void* AllocSprite(size_t mem_req)
 				 * big enough for an additional free block? */
 				if (cur_size == mem_req ||
 						cur_size >= mem_req + sizeof(MemBlock)) {
-					// Set size and in use
+					/* Set size and in use */
 					s->size = mem_req;
 
-					// Do we need to inject a free block too?
+					/* Do we need to inject a free block too? */
 					if (cur_size != mem_req) {
 						NextBlock(s)->size = (cur_size - mem_req) | S_FREE_MASK;
 					}
@@ -377,7 +379,7 @@ static void* AllocSprite(size_t mem_req)
 			}
 		}
 
-		// Reached sentinel, but no block found yet. Delete some old entry.
+		/* Reached sentinel, but no block found yet. Delete some old entry. */
 		DeleteEntryFromSpriteCache();
 	}
 }
@@ -392,12 +394,12 @@ const void *GetRawSprite(SpriteID sprite)
 
 	sc = GetSpriteCache(sprite);
 
-	// Update LRU
+	/* Update LRU */
 	sc->lru = ++_sprite_lru_counter;
 
 	p = sc->ptr;
 
-	// Load the sprite, if it is not loaded, yet
+	/* Load the sprite, if it is not loaded, yet */
 	if (p == NULL) p = ReadSprite(sc, sprite);
 	return p;
 }
@@ -405,12 +407,12 @@ const void *GetRawSprite(SpriteID sprite)
 
 void GfxInitSpriteMem()
 {
-	// initialize sprite cache heap
+	/* initialize sprite cache heap */
 	if (_spritecache_ptr == NULL) _spritecache_ptr = (MemBlock*)malloc(SPRITE_CACHE_SIZE);
 
-	// A big free block
+	/* A big free block */
 	_spritecache_ptr->size = (SPRITE_CACHE_SIZE - sizeof(MemBlock)) | S_FREE_MASK;
-	// Sentinel block (identified by size == 0)
+	/* Sentinel block (identified by size == 0) */
 	NextBlock(_spritecache_ptr)->size = 0;
 
 	/* Reset the spritecache 'pool' */
diff --git a/src/spritecache.h b/src/spritecache.h
index 8fe9772a9..747fbdecb 100644
--- a/src/spritecache.h
+++ b/src/spritecache.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file spritecache.h */
+
 #ifndef SPRITECACHE_H
 #define SPRITECACHE_H
 
diff --git a/src/station.cpp b/src/station.cpp
index 6892c37b4..41fabce7e 100644
--- a/src/station.cpp
+++ b/src/station.cpp
@@ -55,12 +55,12 @@ Station::Station(TileIndex tile)
 }
 
 /**
-	* Clean up a station by clearing vehicle orders and invalidating windows.
-	* Aircraft-Hangar orders need special treatment here, as the hangars are
-	* actually part of a station (tiletype is STATION), but the order type
-	* is OT_GOTO_DEPOT.
-	* @param st Station to be deleted
-	*/
+ * Clean up a station by clearing vehicle orders and invalidating windows.
+ * Aircraft-Hangar orders need special treatment here, as the hangars are
+ * actually part of a station (tiletype is STATION), but the order type
+ * is OT_GOTO_DEPOT.
+ * @param st Station to be deleted
+ */
 Station::~Station()
 {
 	DEBUG(station, cDebugCtorLevel, "I-%3d", index);
@@ -106,7 +106,7 @@ void Station::operator delete(void *p, int st_idx)
 }
 
 /** Called when new facility is built on the station. If it is the first facility
-	* it initializes also 'xy' and 'random_bits' members */
+ * it initializes also 'xy' and 'random_bits' members */
 void Station::AddFacility(byte new_facility_bit, TileIndex facil_xy)
 {
 	if (facilities == 0) {
@@ -182,7 +182,7 @@ bool Station::TileBelongsToRailStation(TileIndex tile) const
 /** Obtain the length of a platform
  * @pre tile must be a railway station tile
  * @param tile A tile that contains the platform in question
- * @returns The length of the platform
+ * @return The length of the platform
  */
 uint Station::GetPlatformLength(TileIndex tile) const
 {
diff --git a/src/station.h b/src/station.h
index 6bd6820d1..3cff76b8a 100644
--- a/src/station.h
+++ b/src/station.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file station.h */
+
 #ifndef STATION_H
 #define STATION_H
 
@@ -82,8 +84,8 @@ protected:
 
 struct StationSpecList {
 	const StationSpec *spec;
-	uint32 grfid;      /// GRF ID of this custom station
-	uint8  localidx;   /// Station ID within GRF of station
+	uint32 grfid;      ///< GRF ID of this custom station
+	uint8  localidx;   ///< Station ID within GRF of station
 };
 
 /** StationRect - used to track station spread out rectangle - cheaper than scanning whole map */
@@ -142,7 +144,7 @@ struct Station {
 	byte facilities;
 	byte airport_type;
 
-	// trainstation width/height
+	/* trainstation width/height */
 	byte trainst_w, trainst_h;
 
 	/** List of custom stations (StationSpecs) allocated to the station */
@@ -151,7 +153,7 @@ struct Station {
 
 	Date build_date;
 
-	uint64 airport_flags;   /// stores which blocks on the airport are taken. was 16 bit earlier on, then 32
+	uint64 airport_flags;   ///< stores which blocks on the airport are taken. was 16 bit earlier on, then 32
 	StationID index;
 
 	byte last_vehicle_type;
diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
index e9bc286c2..582a3e05e 100644
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -118,7 +118,7 @@ static uint FindCatchmentRadius(const Station* st)
 
 static Station* GetStationAround(TileIndex tile, int w, int h, StationID closest_station)
 {
-	// check around to see if there's any stations there
+	/* check around to see if there's any stations there */
 	BEGIN_TILE_LOOP(tile_cur, w + 2, h + 2, tile - TileDiffXY(1, 1))
 		if (IsTileType(tile_cur, MP_STATION)) {
 			StationID t = GetStationIndex(tile_cur);
diff --git a/src/station_gui.cpp b/src/station_gui.cpp
index 6188130a0..e17f9ac56 100644
--- a/src/station_gui.cpp
+++ b/src/station_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file station_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -51,7 +53,8 @@ static StationSortListingTypeFunction StationRatingMaxSorter;
  * goes for the rating: at above 90% orso (224) it is also 'full'
  * Each cargo-bar is 16 pixels wide and 6 pixels high
  * Each rating 14 pixels wide and 1 pixel high and is 1 pixel below the cargo-bar
- * @param x,y X/Y coordinate to draw the box at
+ * @param x coordinate to draw the box at
+ * @param y coordinate to draw the box at
  * @param type Cargo type
  * @param amount Cargo amount
  * @param rating ratings data for that particular cargo */
@@ -230,7 +233,7 @@ static void BuildStationsList(plstations_d* sl, PlayerID owner, byte facilities,
 						}
 					}
 				}
-				//stations without waiting cargo
+				/* stations without waiting cargo */
 				if (num_waiting_cargo == 0 && include_empty) {
 					station_sort[n++] = st;
 				}
@@ -320,7 +323,7 @@ static void PlayerStationsWndProc(Window *w, WindowEvent *e)
 			int cg_ofst;
 			int x = 89;
 			int y = 14;
-			int xb = 2; // offset from left of widget
+			int xb = 2; ///< offset from left of widget
 
 			uint i = 0;
 			for (CargoID c = 0; c < NUM_CARGO; c++) {
@@ -363,7 +366,7 @@ static void PlayerStationsWndProc(Window *w, WindowEvent *e)
 				SetDParam(1, st->facilities);
 				x = DrawString(xb, y, STR_3049_0, 0) + 5;
 
-				// show cargo waiting and station ratings
+				/* show cargo waiting and station ratings */
 				for (CargoID j = 0; j < NUM_CARGO; j++) {
 					uint amount = GB(st->goods[j].waiting_acceptance, 0, 12);
 					if (amount != 0) {
@@ -510,7 +513,7 @@ static void PlayerStationsWndProc(Window *w, WindowEvent *e)
 
 		case WE_DROPDOWN_SELECT: /* we have selected a dropdown item in the list */
 			if (sl->sort_type != e->we.dropdown.index) {
-				// value has changed -> resort
+				/* value has changed -> resort */
 				sl->sort_type = e->we.dropdown.index;
 				station_sort.criteria = sl->sort_type;
 				sl->flags |= SL_RESORT;
diff --git a/src/station_map.cpp b/src/station_map.cpp
index b8c0fda52..afe9d6ad6 100644
--- a/src/station_map.cpp
+++ b/src/station_map.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file station_map.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "station_map.h"
diff --git a/src/station_map.h b/src/station_map.h
index 527a0e5e1..6a4cb6d6b 100644
--- a/src/station_map.h
+++ b/src/station_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file station_map.h */
+
 #ifndef STATION_MAP_H
 #define STATION_MAP_H
 
diff --git a/src/stdafx.h b/src/stdafx.h
index 3c9419f84..b087f9016 100644
--- a/src/stdafx.h
+++ b/src/stdafx.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file stdfax.h */
+
 #ifndef STDAFX_H
 #define STDAFX_H
 
diff --git a/src/string.cpp b/src/string.cpp
index aea4bad9d..b13378b2a 100644
--- a/src/string.cpp
+++ b/src/string.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file string.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -123,7 +125,8 @@ void str_strip_colours(char *str)
  * not found, this is sufficient. If more, or general functionality is
  * needed, look to r7271 where it was removed because it was broken when
  * using certain locales: eg in Turkish the uppercase 'I' was converted to
- * '?', so just revert to the old functionality */
+ * '?', so just revert to the old functionality
+ * @param str string to convert */
 void strtolower(char *str)
 {
 	for (; *str != '\0'; str++) *str = tolower(*str);
diff --git a/src/string.h b/src/string.h
index 2170a30f9..478c533e7 100644
--- a/src/string.h
+++ b/src/string.h
@@ -1,26 +1,28 @@
 /* $Id$ */
 
+/** @file string.h */
+
 #ifndef STRING_H
 #define STRING_H
 
 #include "macros.h"
 
-/*
- * dst: destination buffer
- * src: string to copy/concatenate
- * size: size of the destination buffer
- * usage: ttd_strlcpy(dst, src, lengthof(dst));
+/**
+ * usage ttd_strlcpy(dst, src, lengthof(dst));
+ * @param dst destination buffer
+ * @param src string to copy/concatenate
+ * @param size size of the destination buffer
  */
 void ttd_strlcat(char *dst, const char *src, size_t size);
 void ttd_strlcpy(char *dst, const char *src, size_t size);
 
-/*
- * dst: destination buffer
- * src: string to copy
- * last: pointer to the last element in the dst array
- *       if NULL no boundary check is performed
- * returns a pointer to the terminating \0 in the destination buffer
+/**
  * usage: strecpy(dst, src, lastof(dst));
+ * @param dst destination buffer
+ * @param src string to copy
+ * @param last pointer to the last element in the dst array
+ *             if NULL no boundary check is performed
+ * @return a pointer to the terminating \0 in the destination buffer
  */
 char* strecat(char* dst, const char* src, const char* last);
 char* strecpy(char* dst, const char* src, const char* last);
@@ -38,9 +40,9 @@ void str_strip_colours(char *str);
  * Valid filter types for IsValidChar.
  */
 enum CharSetFilter {
-	CS_ALPHANUMERAL,      //! Both numeric and alphabetic and spaces and stuff
-	CS_NUMERAL,           //! Only numeric ones
-	CS_ALPHA,             //! Only alphabetic values
+	CS_ALPHANUMERAL,      ///< Both numeric and alphabetic and spaces and stuff
+	CS_NUMERAL,           ///< Only numeric ones
+	CS_ALPHA,             ///< Only alphabetic values
 };
 
 /** Convert the given string to lowercase, only works with ASCII! */
@@ -105,6 +107,8 @@ static inline size_t Utf8CharLen(WChar c)
  * Return the length of an UTF-8 encoded value based on a single char. This
  * char should be the first byte of the UTF-8 encoding. If not, or encoding
  * is invalid, return value is 0
+ * @param c char to query length of
+ * @return requested size
  */
 static inline size_t Utf8EncodedCharLen(char c)
 {
@@ -127,7 +131,7 @@ static inline bool IsUtf8Part(char c)
 /**
  * Retrieve the previous UNICODE character in an UTF-8 encoded string.
  * @param s char pointer pointing to (the first char of) the next character
- * @returns a pointer in 's' to the previous UNICODE character's first byte
+ * @return a pointer in 's' to the previous UNICODE character's first byte
  * @note The function should not be used to determine the length of the previous
  * encoded char because it might be an invalid/corrupt start-sequence
  */
diff --git a/src/strings.cpp b/src/strings.cpp
index d7f3ecfd6..d36edc2e7 100644
--- a/src/strings.cpp
+++ b/src/strings.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file strings.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "currency.h"
@@ -37,7 +39,7 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv,
 static char *FormatString(char *buff, const char *str, const int32 *argv, uint casei, const char* last);
 
 struct LanguagePack {
-	uint32 ident;
+	uint32 ident;       // 32-bits identifier
 	uint32 version;     // 32-bits of auto generated version info which is basically a hash of strings.h
 	char name[32];      // the international name of this language
 	char own_name[32];  // the localized name of this language
@@ -45,16 +47,16 @@ struct LanguagePack {
 	uint16 offsets[32]; // the offsets
 	byte plural_form;   // how to compute plural forms
 	byte pad[3];        // pad header to be a multiple of 4
-	char data[VARARRAY_SIZE];
+	char data[VARARRAY_SIZE]; // list of strings
 };
 
 static char **_langpack_offs;
 static LanguagePack *_langpack;
-static uint _langtab_num[32]; // Offset into langpack offs
+static uint _langtab_num[32];   // Offset into langpack offs
 static uint _langtab_start[32]; // Offset into langpack offs
 
 
-// Read an int64 from the argv array.
+/** Read an int64 from the argv array. */
 static inline int64 GetInt64(const int32 **argv)
 {
 	int64 result;
@@ -65,14 +67,14 @@ static inline int64 GetInt64(const int32 **argv)
 	return result;
 }
 
-// Read an int32 from the argv array.
+/** Read an int32 from the argv array. */
 static inline int32 GetInt32(const int32 **argv)
 {
 	assert(argv);
 	return *(*argv)++;
 }
 
-// Read an array from the argv array.
+/** Read an array from the argv array. */
 static inline const int32 *GetArgvPtr(const int32 **argv, int n)
 {
 	const int32 *result;
@@ -85,13 +87,13 @@ static inline const int32 *GetArgvPtr(const int32 **argv, int n)
 
 #define NUM_BOUND_STRINGS 8
 
-// Array to hold the bound strings.
+/* Array to hold the bound strings. */
 static const char *_bound_strings[NUM_BOUND_STRINGS];
 
-// This index is used to implement a "round-robin" allocating of
-// slots for BindCString. NUM_BOUND_STRINGS slots are reserved.
-// Which means that after NUM_BOUND_STRINGS calls to BindCString,
-// the indices will be reused.
+/* This index is used to implement a "round-robin" allocating of
+ * slots for BindCString. NUM_BOUND_STRINGS slots are reserved.
+ * Which means that after NUM_BOUND_STRINGS calls to BindCString,
+ * the indices will be reused. */
 static int _bind_index;
 
 static const char *GetStringPtr(StringID string)
@@ -99,10 +101,16 @@ static const char *GetStringPtr(StringID string)
 	return _langpack_offs[_langtab_start[string >> 11] + (string & 0x7FF)];
 }
 
-// The highest 8 bits of string contain the "case index".
-// These 8 bits will only be set when FormatString wants to print
-// the string in a different case. No one else except FormatString
-// should set those bits, therefore string CANNOT be StringID, but uint32.
+/** The highest 8 bits of string contain the "case index".
+ * These 8 bits will only be set when FormatString wants to print
+ * the string in a different case. No one else except FormatString
+ * should set those bits, therefore string CANNOT be StringID, but uint32.
+ * @param buffr
+ * @param string
+ * @param argv
+ * @param last
+ * @return a formatted string of char
+ */
 static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, const char* last)
 {
 	uint index = GB(string,  0, 11);
@@ -122,8 +130,8 @@ static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, cons
 				return GetSpecialPlayerNameString(buffr, index - 0xE4, argv, last);
 			break;
 
-		// User defined name
 		case 15:
+			/* User defined name */
 			return GetName(buffr, index, last);
 
 		case 26:
@@ -147,8 +155,8 @@ static char *GetStringWithArgs(char *buffr, uint string, const int32 *argv, cons
 			return FormatString(buffr, buff, argv, 0, last);
 
 		case 31:
-			// dynamic strings. These are NOT to be passed through the formatter,
-			// but passed through verbatim.
+			/* dynamic strings. These are NOT to be passed through the formatter,
+			 * but passed through verbatim. */
 			if (index < (STR_SPEC_USERSTRING & 0x7FF)) {
 				return strecpy(buffr, _bound_strings[index], last);
 			}
@@ -184,7 +192,8 @@ char *InlineString(char *buf, StringID string)
  * This function takes a C-string and allocates a temporary string ID.
  * The StringID of the bound string is valid until BindCString is called
  * another NUM_BOUND_STRINGS times. So be careful when using it.
- *
+ * @param str temp string to add
+ * @return the id of that temp string
  * @note formatting a DATE_TINY calls BindCString twice, thus reduces the
  *       amount of 'user' bound strings by 2.
  * @todo rewrite the BindCString system to make the limit flexible and
@@ -198,7 +207,10 @@ StringID BindCString(const char *str)
 	return idx + STR_SPEC_DYNSTRING;
 }
 
-// This function is used to "bind" a C string to a OpenTTD dparam slot.
+/** This function is used to "bind" a C string to a OpenTTD dparam slot.
+ * @param n slot of the string
+ * @param str string to bind
+ */
 void SetDParamStr(uint n, const char *str)
 {
 	SetDParam(n, BindCString(str));
@@ -331,10 +343,10 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n
 	char* p;
 	int j;
 
-	// multiply by exchange rate
+	/* multiply by exchange rate */
 	number *= spec->rate;
 
-	// convert from negative
+	/* convert from negative */
 	if (number < 0) {
 		buff = strecpy(buff, "-", last);
 		number = -number;
@@ -345,7 +357,7 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n
 	 * The only remaining value is 1 (suffix), so everything that is not 1 */
 	if (spec->symbol_pos != 1) buff = strecpy(buff, spec->prefix, last);
 
-	// for huge numbers, compact the number into k or M
+	/* for huge numbers, compact the number into k or M */
 	if (compact) {
 		if (number >= 1000000000) {
 			number = (number + 500000) / 1000000;
@@ -356,7 +368,7 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n
 		}
 	}
 
-	// convert to ascii number and add commas
+	/* convert to ascii number and add commas */
 	p = endof(buf);
 	*--p = '\0';
 	j = 4;
@@ -381,63 +393,63 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, int64 n
 
 static int DeterminePluralForm(int32 n)
 {
-	// The absolute value determines plurality
+	/* The absolute value determines plurality */
 	if (n < 0) n = -n;
 
 	switch (_langpack->plural_form) {
-	// Two forms, singular used for one only
-	// Used in:
-	//   Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish,
-	//   Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto
+	/* Two forms, singular used for one only
+	 * Used in:
+	 *   Danish, Dutch, English, German, Norwegian, Swedish, Estonian, Finnish,
+	 *   Greek, Hebrew, Italian, Portuguese, Spanish, Esperanto */
 	case 0:
 	default:
 		return n != 1;
 
-	// Only one form
-	// Used in:
-	//   Hungarian, Japanese, Korean, Turkish
+	/* Only one form
+	 * Used in:
+	 *   Hungarian, Japanese, Korean, Turkish */
 	case 1:
 		return 0;
 
-	// Two forms, singular used for zero and one
-	// Used in:
-	//   French, Brazilian Portuguese
+	/* Two forms, singular used for zero and one
+	 * Used in:
+	 *   French, Brazilian Portuguese */
 	case 2:
 		return n > 1;
 
-	// Three forms, special case for zero
-	// Used in:
-	//   Latvian
+	/* Three forms, special case for zero
+	 * Used in:
+	 *   Latvian */
 	case 3:
 		return n%10==1 && n%100!=11 ? 0 : n != 0 ? 1 : 2;
 
-	// Three forms, special case for one and two
-	// Used in:
-	//   Gaelige (Irish)
+	/* Three forms, special case for one and two
+	 * Used in:
+	 *   Gaelige (Irish) */
 	case 4:
 		return n==1 ? 0 : n==2 ? 1 : 2;
 
-	// Three forms, special case for numbers ending in 1[2-9]
-	// Used in:
-	//   Lithuanian
+	/* Three forms, special case for numbers ending in 1[2-9]
+	 * Used in:
+	 *   Lithuanian */
 	case 5:
 		return n%10==1 && n%100!=11 ? 0 : n%10>=2 && (n%100<10 || n%100>=20) ? 1 : 2;
 
-	// Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
-	// Used in:
-	//   Croatian, Czech, Russian, Slovak, Ukrainian
+	/* Three forms, special cases for numbers ending in 1 and 2, 3, 4, except those ending in 1[1-4]
+	 * Used in:
+	 *   Croatian, Czech, Russian, Slovak, Ukrainian */
 	case 6:
 		return n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 
-	// Three forms, special case for one and some numbers ending in 2, 3, or 4
-	// Used in:
-	//   Polish
+	/* Three forms, special case for one and some numbers ending in 2, 3, or 4
+	 * Used in:
+	 *   Polish */
 	case 7:
 		return n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2;
 
-	// Four forms, special case for one and all numbers ending in 02, 03, or 04
-	// Used in:
-	//   Slovenian
+	/* Four forms, special case for one and all numbers ending in 02, 03, or 04
+	 * Used in:
+	 *   Slovenian */
 	case 8:
 		return n%100==1 ? 0 : n%100==2 ? 1 : n%100==3 || n%100==4 ? 2 : 3;
 	}
@@ -561,9 +573,9 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 				break;
 
 			case SCC_CARGO_SHORT: { /* {SHORTCARGO} */
-				// Short description of cargotypes. Layout:
-				// 8-bit = cargo type
-				// 16-bit = cargo count
+				/* Short description of cargotypes. Layout:
+				 * 8-bit = cargo type
+				 * 16-bit = cargo count */
 				StringID cargo_str = GetCargo(GetInt32(&argv))->units_volume;
 				switch (cargo_str) {
 					case STR_TONS: {
@@ -599,13 +611,13 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			} break;
 
 			case SCC_CURRENCY_COMPACT_64: { /* {CURRCOMPACT64} */
-				// 64 bit compact currency-unit
+				/* 64 bit compact currency-unit */
 				buff = FormatGenericCurrency(buff, _currency, GetInt64(&argv), true, last);
 				break;
 			}
 
 			case SCC_STRING1: { /* {STRING1} */
-				// String that consumes ONE argument
+				/* String that consumes ONE argument */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 1), last);
 				modifier = 0;
@@ -613,7 +625,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_STRING2: { /* {STRING2} */
-				// String that consumes TWO arguments
+				/* String that consumes TWO arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 2), last);
 				modifier = 0;
@@ -621,7 +633,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_STRING3: { /* {STRING3} */
-				// String that consumes THREE arguments
+				/* String that consumes THREE arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 3), last);
 				modifier = 0;
@@ -629,7 +641,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_STRING4: { /* {STRING4} */
-				// String that consumes FOUR arguments
+				/* String that consumes FOUR arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 4), last);
 				modifier = 0;
@@ -637,7 +649,7 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_STRING5: { /* {STRING5} */
-				// String that consumes FIVE arguments
+				/* String that consumes FIVE arguments */
 				uint str = modifier + GetInt32(&argv);
 				buff = GetStringWithArgs(buff, str, GetArgvPtr(&argv, 5), last);
 				modifier = 0;
@@ -653,11 +665,11 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 				const Industry* i = GetIndustry(GetInt32(&argv));
 				int32 args[2];
 
-				// industry not valid anymore?
+				/* industry not valid anymore? */
 				if (!IsValidIndustry(i)) break;
 
-				// First print the town name and the industry type name
-				// The string STR_INDUSTRY_PATTERN controls the formatting
+				/* First print the town name and the industry type name
+				 * The string STR_INDUSTRY_PATTERN controls the formatting */
 				args[0] = i->town->index;
 				args[1] = GetIndustrySpec(i->type)->name;
 				buff = FormatString(buff, GetStringPtr(STR_INDUSTRY_FORMAT), args, modifier >> 24, last);
@@ -690,9 +702,9 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_CARGO: { // {CARGO}
-				// Layout now is:
-				//   8bit   - cargo type
-				//   16-bit - cargo count
+				/* Layout now is:
+				 *   8bit   - cargo type
+				 *   16-bit - cargo count */
 				CargoID cargo = GetInt32(&argv);
 				StringID cargo_str = (cargo == CT_INVALID) ? (StringID)STR_8838_N_A : GetCargo(cargo)->quantifier;
 				buff = GetStringWithArgs(buff, cargo_str, argv++, last);
@@ -748,17 +760,17 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 				argv++;
 				break;
 
-			// This sets up the gender for the string.
-			// We just ignore this one. It's used in {G 0 Der Die Das} to determine the case.
+			/* This sets up the gender for the string.
+			 * We just ignore this one. It's used in {G 0 Der Die Das} to determine the case. */
 			case SCC_GENDER_INDEX: // {GENDER 0}
 				str++;
 				break;
 
 			case SCC_STRING: {// {STRING}
 				uint str = modifier + GetInt32(&argv);
-				// WARNING. It's prohibited for the included string to consume any arguments.
-				// For included strings that consume argument, you should use STRING1, STRING2 etc.
-				// To debug stuff you can set argv to NULL and it will tell you
+				/* WARNING. It's prohibited for the included string to consume any arguments.
+				 * For included strings that consume argument, you should use STRING1, STRING2 etc.
+				 * To debug stuff you can set argv to NULL and it will tell you */
 				buff = GetStringWithArgs(buff, str, argv, last);
 				modifier = 0;
 				break;
@@ -834,23 +846,23 @@ static char* FormatString(char* buff, const char* str, const int32* argv, uint c
 			}
 
 			case SCC_SETCASE: { // {SETCASE}
-				// This is a pseudo command, it's outputted when someone does {STRING.ack}
-				// The modifier is added to all subsequent GetStringWithArgs that accept the modifier.
+				/* This is a pseudo command, it's outputted when someone does {STRING.ack}
+				 * The modifier is added to all subsequent GetStringWithArgs that accept the modifier. */
 				modifier = (byte)*str++ << 24;
 				break;
 			}
 
 			case SCC_SWITCH_CASE: { // {Used to implement case switching}
-				// <0x9E> <NUM CASES> <CASE1> <LEN1> <STRING1> <CASE2> <LEN2> <STRING2> <CASE3> <LEN3> <STRING3> <STRINGDEFAULT>
-				// Each LEN is printed using 2 bytes in big endian order.
+				/* <0x9E> <NUM CASES> <CASE1> <LEN1> <STRING1> <CASE2> <LEN2> <STRING2> <CASE3> <LEN3> <STRING3> <STRINGDEFAULT>
+				 * Each LEN is printed using 2 bytes in big endian order. */
 				uint num = (byte)*str++;
 				while (num) {
 					if ((byte)str[0] == casei) {
-						// Found the case, adjust str pointer and continue
+						/* Found the case, adjust str pointer and continue */
 						str += 3;
 						break;
 					}
-					// Otherwise skip to the next case
+					/* Otherwise skip to the next case */
 					str += 3 + (str[1] << 8) + str[2];
 					num--;
 				}
@@ -1018,20 +1030,20 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv,
 			return strecpy(buff, origin_songs_specs[GetInt32(&argv) - 1].song_name, last);
 	}
 
-	// town name?
+	/* town name? */
 	if (IS_INT_INSIDE(ind - 6, 0, SPECSTR_TOWNNAME_LAST-SPECSTR_TOWNNAME_START + 1)) {
 		buff = GetSpecialTownNameString(buff, ind - 6, GetInt32(&argv), last);
 		return strecpy(buff, " Transport", last);
 	}
 
-	// language name?
+	/* language name? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_LANGUAGE_START - 0x70E4), (SPECSTR_LANGUAGE_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_LANGUAGE_START - 0x70E4);
 		return strecpy(buff,
 			i == _dynlang.curr ? _langpack->own_name : _dynlang.ent[i].name, last);
 	}
 
-	// resolution size?
+	/* resolution size? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_RESOLUTION_START - 0x70E4), (SPECSTR_RESOLUTION_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_RESOLUTION_START - 0x70E4);
 		buff += snprintf(
@@ -1040,7 +1052,7 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv,
 		return buff;
 	}
 
-	// screenshot format name?
+	/* screenshot format name? */
 	if (IS_INT_INSIDE(ind, (SPECSTR_SCREENSHOT_START - 0x70E4), (SPECSTR_SCREENSHOT_END - 0x70E4) + 1)) {
 		int i = ind - (SPECSTR_SCREENSHOT_START - 0x70E4);
 		return strecpy(buff, GetScreenshotFormatDesc(i), last);
@@ -1050,7 +1062,10 @@ static char *GetSpecialPlayerNameString(char *buff, int ind, const int32 *argv,
 	return NULL;
 }
 
-// remap a string ID from the old format to the new format
+/**
+ * remap a string ID from the old format to the new format
+ * @param s StringID that requires remapping
+ * @return translated ID*/
 StringID RemapOldStringID(StringID s)
 {
 	switch (s) {
@@ -1103,10 +1118,10 @@ bool ReadLanguagePack(int lang_index)
 		tot_count += num;
 	}
 
-	// Allocate offsets
+	/* Allocate offsets */
 	langpack_offs = MallocT<char*>(tot_count);
 
-	// Fill offsets
+	/* Fill offsets */
 	s = lang_pack->data;
 	for (i = 0; i != tot_count; i++) {
 		len = (byte)*s;
@@ -1133,7 +1148,7 @@ bool ReadLanguagePack(int lang_index)
 /** Determine the current charset based on the environment
  * First check some default values, after this one we passed ourselves
  * and if none exist return the value for $LANG
- * @param environment variable to check conditionally if default ones are not
+ * @param param environment variable to check conditionally if default ones are not
  *        set. Pass NULL if you don't want additional checks.
  * @return return string containing current charset, or NULL if not-determinable */
 const char *GetCurrentLocale(const char *param)
diff --git a/src/strings.h b/src/strings.h
index 56893346c..3b220f4ba 100644
--- a/src/strings.h
+++ b/src/strings.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file strings.h */
+
 #ifndef STRINGS_H
 #define STRINGS_H
 
diff --git a/src/subsidy_gui.cpp b/src/subsidy_gui.cpp
index fc4edec04..ce3e48da0 100644
--- a/src/subsidy_gui.cpp
+++ b/src/subsidy_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file subsidy_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"