(svn r9568) -Documentation: doxygen and comment changes: Root of src is finally done. Now, time to start clearing as much as possible

13 files changed, 192 insertions, 124 deletions

diff --git a/src/dedicated.cpp b/src/dedicated.cpp
index 9de472df5..8acf58022 100644
--- a/src/dedicated.cpp
+++ b/src/dedicated.cpp
@@ -63,6 +63,7 @@ void DedicatedFork()
 
 #else
 
+/** Empty helper function call for NOT(UNIX and not MORPHOS) systems */
 void DedicatedFork() {}
 
 #endif /* ENABLE_NETWORK */
diff --git a/src/direction.h b/src/direction.h
index d0dd988eb..837fa149f 100644
--- a/src/direction.h
+++ b/src/direction.h
@@ -24,7 +24,7 @@ enum Direction {
 
 /** Define basic enum properties */
 template <> struct EnumPropsT<Direction> : MakeEnumPropsT<Direction, byte, DIR_BEGIN, DIR_END, INVALID_DIR> {};
-typedef TinyEnumT<Direction> DirectionByte;
+typedef TinyEnumT<Direction> DirectionByte; //typedefing-enumification of Direction
 
 static inline Direction ReverseDir(Direction d)
 {
@@ -73,7 +73,7 @@ DECLARE_POSTFIX_INCREMENT(DiagDirection);
 
 /** Define basic enum properties */
 template <> struct EnumPropsT<DiagDirection> : MakeEnumPropsT<DiagDirection, byte, DIAGDIR_BEGIN, DIAGDIR_END, INVALID_DIAGDIR> {};
-typedef TinyEnumT<DiagDirection> DiagDirectionByte;
+typedef TinyEnumT<DiagDirection> DiagDirectionByte; //typedefing-enumification of DiagDirection
 
 static inline DiagDirection ReverseDiagDir(DiagDirection d)
 {
@@ -137,7 +137,9 @@ static inline DiagDirection AxisToDiagDir(Axis a)
 
 /**
  * Convert an axis and a flag for north/south into a DiagDirection
+ * @param xy axis to convert
  * @param ns north -> 0, south -> 1
+ * @return the desired DiagDirection
  */
 static inline DiagDirection XYNSToDiagDir(Axis xy, uint ns)
 {
diff --git a/src/economy.cpp b/src/economy.cpp
index b3d635a02..aafad4a37 100644
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -1690,6 +1690,7 @@ extern int GetAmountOwnedBy(const Player *p, PlayerID owner);
 
 /** Acquire shares in an opposing company.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 player to buy the shares from
  * @param p2 unused
  */
@@ -1735,6 +1736,7 @@ int32 CmdBuyShareInCompany(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Sell shares in an opposing company.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 player to sell the shares from
  * @param p2 unused
  */
@@ -1770,6 +1772,7 @@ int32 CmdSellShareInCompany(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
  * that company.
  * @todo currently this only works for AI players
  * @param tile unused
+ * @param flags type of operation
  * @param p1 player/company to buy up
  * @param p2 unused
  */
diff --git a/src/endian_check.cpp b/src/endian_check.cpp
index 1cccb89eb..9c6fe7125 100644
--- a/src/endian_check.cpp
+++ b/src/endian_check.cpp
@@ -12,6 +12,10 @@
 #include <stdio.h>
 #include <string.h>
 
+/** Main call of the endian_check program
+ * @param argc argument count
+ * @param argv arguments themselves
+ * @return exit code */
 int main (int argc, char *argv[]) {
 	unsigned char EndianTest[2] = { 1, 0 };
 	int force_BE = 0, force_LE = 0, force_PREPROCESSOR = 0;
diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp
index 35a4e0030..be8e871ed 100644
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -656,7 +656,7 @@ int32 CmdBuildSingleSignal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			/* convert signals <-> semaphores */
 			cost = _price.build_signals + _price.remove_signals;
 		} else {
-			// it is free to change orientation/pre-exit-combo signals
+			/* it is free to change orientation/pre-exit-combo signals */
 			cost = 0;
 		}
 	}
@@ -741,7 +741,7 @@ static int32 CmdSignalTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint3
 
 	track = TrackdirToTrack(trackdir); /* trackdir might have changed, keep track in sync */
 
-	// copy the signal-style of the first rail-piece if existing
+	/* copy the signal-style of the first rail-piece if existing */
 	if (HasSignals(tile)) {
 		signals = _m[tile].m3 & SignalOnTrack(track);
 		if (signals == 0) signals = SignalOnTrack(track); /* Can this actually occur? */
diff --git a/src/water_cmd.cpp b/src/water_cmd.cpp
index 429583eac..c20983325 100644
--- a/src/water_cmd.cpp
+++ b/src/water_cmd.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file water_cmd.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "bridge_map.h"
@@ -47,6 +49,7 @@ static void FloodVehicle(Vehicle *v);
 
 /** Build a ship depot.
  * @param tile tile where ship depot is built
+ * @param flags type of operation
  * @param p1 bit 0 depot orientation (Axis)
  * @param p2 unused
  */
@@ -76,7 +79,7 @@ int32 CmdBuildShipDepot(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	ret = DoCommand(tile2, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 	if (CmdFailed(ret)) return CMD_ERROR;
 
-	// pretend that we're not making land from the water even though we actually are.
+	/* pretend that we're not making land from the water even though we actually are. */
 	cost = 0;
 
 	depot = AllocateDepot();
@@ -120,25 +123,25 @@ static int32 RemoveShipDepot(TileIndex tile, uint32 flags)
 	return _price.remove_ship_depot;
 }
 
-// build a shiplift
+/** build a shiplift */
 static int32 DoBuildShiplift(TileIndex tile, DiagDirection dir, uint32 flags)
 {
 	int32 ret;
 	int delta;
 
-	// middle tile
+	/* middle tile */
 	ret = DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 	if (CmdFailed(ret)) return CMD_ERROR;
 
 	delta = TileOffsByDiagDir(dir);
-	// lower tile
+	/* lower tile */
 	ret = DoCommand(tile - delta, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 	if (CmdFailed(ret)) return CMD_ERROR;
 	if (GetTileSlope(tile - delta, NULL) != SLOPE_FLAT) {
 		return_cmd_error(STR_1000_LAND_SLOPED_IN_WRONG_DIRECTION);
 	}
 
-	// upper tile
+	/* upper tile */
 	ret = DoCommand(tile + delta, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 	if (CmdFailed(ret)) return CMD_ERROR;
 	if (GetTileSlope(tile + delta, NULL) != SLOPE_FLAT) {
@@ -167,7 +170,7 @@ static int32 RemoveShiplift(TileIndex tile, uint32 flags)
 
 	if (!CheckTileOwnership(tile)) return CMD_ERROR;
 
-	// make sure no vehicle is on the tile.
+	/* make sure no vehicle is on the tile. */
 	if (!EnsureNoVehicle(tile) || !EnsureNoVehicle(tile + delta) || !EnsureNoVehicle(tile - delta))
 		return CMD_ERROR;
 
@@ -190,6 +193,7 @@ static void MarkTilesAroundDirty(TileIndex tile)
 
 /** Builds a lock (ship-lift)
  * @param tile tile where to place the lock
+ * @param flags type of operation
  * @param p1 unused
  * @param p2 unused
  */
@@ -211,6 +215,7 @@ int32 CmdBuildLock(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Build a piece of canal.
  * @param tile end tile of stretch-dragging
+ * @param flags type of operation
  * @param p1 start tile of stretch-dragging
  * @param p2 ctrl pressed - toggles ocean / canals at sealevel (ocean only allowed in the scenario editor)
  */
@@ -249,7 +254,7 @@ int32 CmdBuildCanal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			return_cmd_error(STR_0007_FLAT_LAND_REQUIRED);
 		}
 
-		// can't make water of water!
+		/* can't make water of water! */
 		if (IsTileType(tile, MP_WATER) && (!IsTileOwner(tile, OWNER_WATER) || HASBIT(p2, 0))) continue;
 
 		ret = DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
@@ -282,10 +287,10 @@ static int32 ClearTile_Water(TileIndex tile, byte flags)
 		case WATER_TILE_CLEAR:
 			if (flags & DC_NO_WATER) return_cmd_error(STR_3807_CAN_T_BUILD_ON_WATER);
 
-			// Make sure no vehicle is on the tile
+			/* Make sure no vehicle is on the tile */
 			if (!EnsureNoVehicle(tile)) return CMD_ERROR;
 
-			// Make sure it's not an edge tile.
+			/* Make sure it's not an edge tile. */
 			if (!IS_INT_INSIDE(TileX(tile), 1, MapMaxX() - 1) ||
 					!IS_INT_INSIDE(TileY(tile), 1, MapMaxY() - 1)) {
 				return_cmd_error(STR_0002_TOO_CLOSE_TO_EDGE_OF_MAP);
@@ -299,10 +304,10 @@ static int32 ClearTile_Water(TileIndex tile, byte flags)
 		case WATER_TILE_COAST: {
 			Slope slope = GetTileSlope(tile, NULL);
 
-			// Make sure no vehicle is on the tile
+			/* Make sure no vehicle is on the tile */
 			if (!EnsureNoVehicle(tile)) return CMD_ERROR;
 
-			// Make sure it's not an edge tile.
+			/* Make sure it's not an edge tile. */
 			if (!IS_INT_INSIDE(TileX(tile), 1, MapMaxX() - 1) ||
 					!IS_INT_INSIDE(TileY(tile), 1, MapMaxY() - 1)) {
 				return_cmd_error(STR_0002_TOO_CLOSE_TO_EDGE_OF_MAP);
@@ -325,7 +330,7 @@ static int32 ClearTile_Water(TileIndex tile, byte flags)
 
 			if (flags & DC_AUTO) return_cmd_error(STR_2004_BUILDING_MUST_BE_DEMOLISHED);
 			if (_current_player == OWNER_WATER) return CMD_ERROR;
-			// move to the middle tile..
+			/* move to the middle tile.. */
 			return RemoveShiplift(tile + ToTileIndexDiff(_shiplift_tomiddle_offs[GetSection(tile)]), flags);
 		}
 
@@ -339,7 +344,7 @@ static int32 ClearTile_Water(TileIndex tile, byte flags)
 	}
 }
 
-// return true if a tile is a water tile.
+/** return true if a tile is a water tile. */
 static bool IsWateredTile(TileIndex tile)
 {
 	switch (GetTileType(tile)) {
@@ -362,12 +367,12 @@ static bool IsWateredTile(TileIndex tile)
 	}
 }
 
-// draw a canal styled water tile with dikes around
+/** draw a canal styled water tile with dikes around */
 void DrawCanalWater(TileIndex tile)
 {
 	uint wa;
 
-	// determine the edges around with water.
+	/* determine the edges around with water. */
 	wa = IsWateredTile(TILE_ADDXY(tile, -1, 0)) << 0;
 	wa += IsWateredTile(TILE_ADDXY(tile, 0, 1)) << 1;
 	wa += IsWateredTile(TILE_ADDXY(tile, 1, 0)) << 2;
@@ -378,25 +383,25 @@ void DrawCanalWater(TileIndex tile)
 	if (!(wa & 4)) DrawGroundSprite(SPR_CANALS_BASE + 59, PAL_NONE);
 	if (!(wa & 8)) DrawGroundSprite(SPR_CANALS_BASE + 60, PAL_NONE);
 
-	// right corner
+	/* right corner */
 	switch (wa & 0x03) {
 		case 0: DrawGroundSprite(SPR_CANALS_BASE + 57 + 4, PAL_NONE); break;
 		case 3: if (!IsWateredTile(TILE_ADDXY(tile, -1, 1))) DrawGroundSprite(SPR_CANALS_BASE + 57 + 8, PAL_NONE); break;
 	}
 
-	// bottom corner
+	/* bottom corner */
 	switch (wa & 0x06) {
 		case 0: DrawGroundSprite(SPR_CANALS_BASE + 57 + 5, PAL_NONE); break;
 		case 6: if (!IsWateredTile(TILE_ADDXY(tile, 1, 1))) DrawGroundSprite(SPR_CANALS_BASE + 57 + 9, PAL_NONE); break;
 	}
 
-	// left corner
+	/* left corner */
 	switch (wa & 0x0C) {
 		case  0: DrawGroundSprite(SPR_CANALS_BASE + 57 + 6, PAL_NONE); break;
 		case 12: if (!IsWateredTile(TILE_ADDXY(tile, 1, -1))) DrawGroundSprite(SPR_CANALS_BASE + 57 + 10, PAL_NONE); break;
 	}
 
-	// upper corner
+	/* upper corner */
 	switch (wa & 0x09) {
 		case 0: DrawGroundSprite(SPR_CANALS_BASE + 57 + 7, PAL_NONE); break;
 		case 9: if (!IsWateredTile(TILE_ADDXY(tile, -1, -1))) DrawGroundSprite(SPR_CANALS_BASE + 57 + 11, PAL_NONE); break;
@@ -524,7 +529,7 @@ static void TileLoopWaterHelper(TileIndex tile, const TileIndexDiffC *offs)
 {
 	TileIndex target = TILE_ADD(tile, ToTileIndexDiff(offs[0]));
 
-	// type of this tile mustn't be water already.
+	/* type of this tile mustn't be water already. */
 	if (IsTileType(target, MP_WATER)) return;
 
 	if (TileHeight(TILE_ADD(tile, ToTileIndexDiff(offs[1]))) != 0 ||
@@ -534,7 +539,7 @@ static void TileLoopWaterHelper(TileIndex tile, const TileIndexDiffC *offs)
 
 	if (TileHeight(TILE_ADD(tile, ToTileIndexDiff(offs[3]))) != 0 ||
 			TileHeight(TILE_ADD(tile, ToTileIndexDiff(offs[4]))) != 0) {
-		// make coast..
+		/* make coast.. */
 		switch (GetTileType(target)) {
 			case MP_RAILWAY: {
 				TrackBits tracks;
@@ -626,7 +631,7 @@ static void FloodVehicle(Vehicle *v)
 			u = v;
 			if (IsFrontEngine(v)) pass = 4; // driver
 
-			// crash all wagons, and count passangers
+			/* crash all wagons, and count passangers */
 			BEGIN_ENUM_WAGONS(v)
 				if (IsCargoInClass(v->cargo_type, CC_PASSENGERS)) pass += v->cargo_count;
 				v->vehstatus |= VS_CRASHED;
@@ -653,7 +658,7 @@ static void FloodVehicle(Vehicle *v)
 	}
 }
 
-// called from tunnelbridge_cmd, and by TileLoop_Industry()
+/** called from tunnelbridge_cmd, and by TileLoop_Industry() */
 void TileLoop_Water(TileIndex tile)
 {
 	static const TileIndexDiffC _tile_loop_offs_array[][5] = {
@@ -675,11 +680,10 @@ void TileLoop_Water(TileIndex tile)
 			TileLoopWaterHelper(tile, _tile_loop_offs_array[i]);
 		}
 	}
-	// _current_player can be changed by TileLoopWaterHelper.. reset it back
-	//   here
+	/* _current_player can be changed by TileLoopWaterHelper.. reset it back here */
 	_current_player = OWNER_NONE;
 
-	// edges
+	/* edges */
 	if (TileX(tile) == 0 && IS_INT_INSIDE(TileY(tile), 1, MapSizeY() - 3 + 1)) { //NE
 		TileLoopWaterHelper(tile, _tile_loop_offs_array[2]);
 	}
@@ -713,11 +717,11 @@ static uint32 GetTileTrackStatus_Water(TileIndex tile, TransportType mode)
 		default: return 0;
 	}
 	if (TileX(tile) == 0) {
-		// NE border: remove tracks that connects NE tile edge
+		/* NE border: remove tracks that connects NE tile edge */
 		ts &= ~(TRACK_BIT_X | TRACK_BIT_UPPER | TRACK_BIT_RIGHT);
 	}
 	if (TileY(tile) == 0) {
-		// NW border: remove tracks that connects NW tile edge
+		/* NW border: remove tracks that connects NW tile edge */
 		ts &= ~(TRACK_BIT_Y | TRACK_BIT_LEFT | TRACK_BIT_UPPER);
 	}
 	return ts * 0x101;
diff --git a/src/water_map.h b/src/water_map.h
index 1f769c9af..cb20bd15a 100644
--- a/src/water_map.h
+++ b/src/water_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file water_map.h */
+
 #ifndef WATER_MAP_H
 #define WATER_MAP_H
 
diff --git a/src/waypoint.cpp b/src/waypoint.cpp
index 919c96faa..a7e02d6f1 100644
--- a/src/waypoint.cpp
+++ b/src/waypoint.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file waypoint.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 
@@ -39,7 +41,9 @@ static void WaypointPoolNewBlock(uint start_item)
 
 DEFINE_OLD_POOL(Waypoint, Waypoint, WaypointPoolNewBlock, NULL)
 
-/* Create a new waypoint */
+/**
+ * Create a new waypoint
+ * @return a pointer to the newly created Waypoint */
 static Waypoint* AllocateWaypoint()
 {
 	Waypoint *wp;
@@ -63,7 +67,9 @@ static Waypoint* AllocateWaypoint()
 	return NULL;
 }
 
-/* Update the sign for the waypoint */
+/**
+ * Update the sign for the waypoint
+ * @param wp Waypoint to update sign */
 static void UpdateWaypointSign(Waypoint* wp)
 {
 	Point pt = RemapCoords2(TileX(wp->xy) * TILE_SIZE, TileY(wp->xy) * TILE_SIZE);
@@ -71,7 +77,9 @@ static void UpdateWaypointSign(Waypoint* wp)
 	UpdateViewportSignPos(&wp->sign, pt.x, pt.y - 0x20, STR_WAYPOINT_VIEWPORT);
 }
 
-/* Redraw the sign of a waypoint */
+/**
+ * Redraw the sign of a waypoint
+ * @param wp Waypoint to redraw sign */
 static void RedrawWaypointSign(const Waypoint* wp)
 {
 	MarkAllViewportsDirty(
@@ -81,7 +89,9 @@ static void RedrawWaypointSign(const Waypoint* wp)
 		wp->sign.top + 48);
 }
 
-/* Update all signs */
+/**
+ * Update all signs
+ */
 void UpdateAllWaypointSigns()
 {
 	Waypoint *wp;
@@ -91,7 +101,10 @@ void UpdateAllWaypointSigns()
 	}
 }
 
-/* Internal handler to delete a waypoint */
+/**
+ * Internal handler to delete a waypoint
+ * @param wp Waypoint to delete
+ */
 void DestroyWaypoint(Waypoint *wp)
 {
 	RemoveOrderFromAllVehicles(OT_GOTO_WAYPOINT, wp->index);
@@ -101,7 +114,10 @@ void DestroyWaypoint(Waypoint *wp)
 	RedrawWaypointSign(wp);
 }
 
-/* Set the default name for a waypoint */
+/**
+ * Set the default name for a waypoint
+ * @param wp Waypoint to work on
+ */
 static void MakeDefaultWaypointName(Waypoint* wp)
 {
 	Waypoint *local_wp;
@@ -127,7 +143,10 @@ static void MakeDefaultWaypointName(Waypoint* wp)
 	wp->town_cn = i;
 }
 
-/* Find a deleted waypoint close to a tile. */
+/**
+ * Find a deleted waypoint close to a tile.
+ * @param tile to search from
+ */
 static Waypoint *FindDeletedWaypointCloseTo(TileIndex tile)
 {
 	Waypoint *wp, *best = NULL;
@@ -173,6 +192,7 @@ void AfterLoadWaypoints()
 /** Convert existing rail to waypoint. Eg build a waypoint station over
  * piece of rail
  * @param tile tile where waypoint will be built
+ * @param flags type of operation
  * @param p1 graphics for waypoint type, 0 indicates standard graphics
  * @param p2 unused
  *
@@ -233,7 +253,7 @@ int32 CmdBuildTrainWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			wp->grfid = statspec->grfid;
 			wp->localidx = statspec->localidx;
 		} else {
-			// Specified custom graphics do not exist, so use default.
+			/* Specified custom graphics do not exist, so use default. */
 			wp->stat_id = 0;
 			wp->grfid = 0;
 			wp->localidx = 0;
@@ -253,7 +273,9 @@ int32 CmdBuildTrainWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	return _price.build_train_depot;
 }
 
-/* Daily loop for waypoints */
+/**
+ * Daily loop for waypoints
+ */
 void WaypointsDailyLoop()
 {
 	Waypoint *wp;
@@ -264,7 +286,13 @@ void WaypointsDailyLoop()
 	}
 }
 
-/* Remove a waypoint */
+/**
+ * Remove a waypoint
+ * @param tile from which to remove waypoint
+ * @param flags type of operation
+ * @param justremove will indicate if it is removed from rail or if rails are removed too
+ * @return cost of operation or error
+ */
 int32 RemoveTrainWaypoint(TileIndex tile, uint32 flags, bool justremove)
 {
 	Waypoint *wp;
@@ -297,10 +325,13 @@ int32 RemoveTrainWaypoint(TileIndex tile, uint32 flags, bool justremove)
 	return _price.remove_train_depot;
 }
 
-/** Delete a waypoint
+/**
+ * Delete a waypoint
  * @param tile tile where waypoint is to be deleted
+ * @param flags type of operation
  * @param p1 unused
  * @param p2 unused
+ * @return cost of operation or error
  */
 int32 CmdRemoveTrainWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -308,10 +339,13 @@ int32 CmdRemoveTrainWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	return RemoveTrainWaypoint(tile, flags, true);
 }
 
-/** Rename a waypoint.
+/**
+ * Rename a waypoint.
  * @param tile unused
+ * @param flags type of operation
  * @param p1 id of waypoint
  * @param p2 unused
+ * @return cost of operation or error
  */
 int32 CmdRenameWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
@@ -349,7 +383,11 @@ int32 CmdRenameWaypoint(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	return 0;
 }
 
-/* This hacks together some dummy one-shot Station structure for a waypoint. */
+/**
+ * This hacks together some dummy one-shot Station structure for a waypoint.
+ * @param tile on which to work
+ * @return pointer to a Station
+ */
 Station *ComposeWaypointStation(TileIndex tile)
 {
 	Waypoint *wp = GetWaypointByTile(tile);
@@ -367,7 +405,13 @@ Station *ComposeWaypointStation(TileIndex tile)
 	return &stat;
 }
 
-/* Draw a waypoint */
+/**
+ * Draw a waypoint
+ * @param x coordinate
+ * @param y coordinate
+ * @param stat_id station id
+ * @param railtype RailType to use for
+ */
 void DrawWaypointSprite(int x, int y, int stat_id, RailType railtype)
 {
 	x += 33;
@@ -378,7 +422,9 @@ void DrawWaypointSprite(int x, int y, int stat_id, RailType railtype)
 	}
 }
 
-/* Fix savegames which stored waypoints in their old format */
+/**
+ * Fix savegames which stored waypoints in their old format
+ */
 void FixOldWaypoints()
 {
 	Waypoint *wp;
diff --git a/src/waypoint.h b/src/waypoint.h
index 2a34d1104..9f268bfd6 100644
--- a/src/waypoint.h
+++ b/src/waypoint.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file waypoint.h */
+
 #ifndef WAYPOINT_H
 #define WAYPOINT_H
 
@@ -28,6 +30,8 @@ DECLARE_OLD_POOL(Waypoint, Waypoint, 3, 8000)
 
 /**
  * Check if a Waypoint really exists.
+ * @param wp Waypoint to query
+ * @return the validity of the waypoint
  */
 static inline bool IsValidWaypoint(const Waypoint *wp)
 {
diff --git a/src/widget.cpp b/src/widget.cpp
index 8d564ac8f..d0244a184 100644
--- a/src/widget.cpp
+++ b/src/widget.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file widget.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -52,7 +54,7 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 
 	switch (wi->type) {
 		case WWT_SCROLLBAR: {
-			// vertical scroller
+			/* vertical scroller */
 			w->flags4 &= ~WF_HSCROLL;
 			w->flags4 &= ~WF_SCROLL2;
 			mi = wi->top;
@@ -62,7 +64,7 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 			break;
 		}
 		case WWT_SCROLL2BAR: {
-			// 2nd vertical scroller
+			/* 2nd vertical scroller */
 			w->flags4 &= ~WF_HSCROLL;
 			w->flags4 |= WF_SCROLL2;
 			mi = wi->top;
@@ -72,7 +74,7 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 			break;
 		}
 		case  WWT_HSCROLLBAR: {
-			// horizontal scroller
+			/* horizontal scroller */
 			w->flags4 &= ~WF_SCROLL2;
 			w->flags4 |= WF_HSCROLL;
 			mi = wi->left;
@@ -84,7 +86,7 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 		default: return; //this should never happen
 	}
 	if (pos <= mi+9) {
-		// Pressing the upper button?
+		/* Pressing the upper button? */
 		w->flags4 |= WF_SCROLL_UP;
 		if (_scroller_click_timeout == 0) {
 			_scroller_click_timeout = 6;
@@ -92,7 +94,7 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 		}
 		_left_button_clicked = false;
 	} else if (pos >= ma-10) {
-		// Pressing the lower button?
+		/* Pressing the lower button? */
 		w->flags4 |= WF_SCROLL_DOWN;
 
 		if (_scroller_click_timeout == 0) {
@@ -102,7 +104,6 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 		}
 		_left_button_clicked = false;
 	} else {
-		//
 		Point pt = HandleScrollbarHittest(sb, mi, ma);
 
 		if (pos < pt.x) {
@@ -127,7 +128,8 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
 /** Returns the index for the widget located at the given position
  * relative to the window. It includes all widget-corner pixels as well.
  * @param *w Window to look inside
- * @param  x,y Window client coordinates
+ * @param  x
+ * @param  y Window client coordinates
  * @return A widget index, or -1 if no widget was found.
  */
 int GetWidgetFromPos(const Window *w, int x, int y)
@@ -135,8 +137,8 @@ int GetWidgetFromPos(const Window *w, int x, int y)
 	uint index;
 	int found_index = -1;
 
-	// Go through the widgets and check if we find the widget that the coordinate is
-	// inside.
+	/* Go through the widgets and check if we find the widget that the coordinate is
+	 * inside. */
 	for (index = 0; index < w->widget_count; index++) {
 		const Widget *wi = &w->widget[index];
 		if (wi->type == WWT_EMPTY || wi->type == WWT_FRAME) continue;
@@ -294,14 +296,14 @@ void DrawWindowWidgets(const Window *w)
 			goto draw_default;
 		}
 
-		// vertical scrollbar
+		/* vertical scrollbar */
 		case WWT_SCROLLBAR: {
 			Point pt;
 			int c1,c2;
 
 			assert(r.right - r.left == 11); // XXX - to ensure the same sizes are used everywhere!
 
-			// draw up/down buttons
+			/* draw up/down buttons */
 			clicked = ((w->flags4 & (WF_SCROLL_UP | WF_HSCROLL | WF_SCROLL2)) == WF_SCROLL_UP);
 			DrawFrameRect(r.left, r.top, r.right, r.top + 9, wi->color, (clicked) ? FR_LOWERED : FR_NONE);
 			DoDrawString(UPARROW, r.left + 2 + clicked, r.top + clicked, 0x10);
@@ -313,11 +315,11 @@ void DrawWindowWidgets(const Window *w)
 			c1 = _colour_gradient[wi->color&0xF][3];
 			c2 = _colour_gradient[wi->color&0xF][7];
 
-			// draw "shaded" background
+			/* draw "shaded" background */
 			GfxFillRect(r.left, r.top+10, r.right, r.bottom-10, c2);
 			GfxFillRect(r.left, r.top+10, r.right, r.bottom-10, c1 | (1 << PALETTE_MODIFIER_GREYOUT));
 
-			// draw shaded lines
+			/* draw shaded lines */
 			GfxFillRect(r.left+2, r.top+10, r.left+2, r.bottom-10, c1);
 			GfxFillRect(r.left+3, r.top+10, r.left+3, r.bottom-10, c2);
 			GfxFillRect(r.left+7, r.top+10, r.left+7, r.bottom-10, c1);
@@ -333,7 +335,7 @@ void DrawWindowWidgets(const Window *w)
 
 			assert(r.right - r.left == 11); // XXX - to ensure the same sizes are used everywhere!
 
-			// draw up/down buttons
+			/* draw up/down buttons */
 			clicked = ((w->flags4 & (WF_SCROLL_UP | WF_HSCROLL | WF_SCROLL2)) == (WF_SCROLL_UP | WF_SCROLL2));
 			DrawFrameRect(r.left, r.top, r.right, r.top + 9, wi->color,  (clicked) ? FR_LOWERED : FR_NONE);
 			DoDrawString(UPARROW, r.left + 2 + clicked, r.top + clicked, 0x10);
@@ -345,11 +347,11 @@ void DrawWindowWidgets(const Window *w)
 			c1 = _colour_gradient[wi->color&0xF][3];
 			c2 = _colour_gradient[wi->color&0xF][7];
 
-			// draw "shaded" background
+			/* draw "shaded" background */
 			GfxFillRect(r.left, r.top+10, r.right, r.bottom-10, c2);
 			GfxFillRect(r.left, r.top+10, r.right, r.bottom-10, c1 | (1 << PALETTE_MODIFIER_GREYOUT));
 
-			// draw shaded lines
+			/* draw shaded lines */
 			GfxFillRect(r.left+2, r.top+10, r.left+2, r.bottom-10, c1);
 			GfxFillRect(r.left+3, r.top+10, r.left+3, r.bottom-10, c2);
 			GfxFillRect(r.left+7, r.top+10, r.left+7, r.bottom-10, c1);
@@ -360,7 +362,7 @@ void DrawWindowWidgets(const Window *w)
 			break;
 		}
 
-		// horizontal scrollbar
+		/* horizontal scrollbar */
 		case WWT_HSCROLLBAR: {
 			Point pt;
 			int c1,c2;
@@ -378,17 +380,17 @@ void DrawWindowWidgets(const Window *w)
 			c1 = _colour_gradient[wi->color&0xF][3];
 			c2 = _colour_gradient[wi->color&0xF][7];
 
-			// draw "shaded" background
+			/* draw "shaded" background */
 			GfxFillRect(r.left+10, r.top, r.right-10, r.bottom, c2);
 			GfxFillRect(r.left+10, r.top, r.right-10, r.bottom, c1 | (1 << PALETTE_MODIFIER_GREYOUT));
 
-			// draw shaded lines
+			/* draw shaded lines */
 			GfxFillRect(r.left+10, r.top+2, r.right-10, r.top+2, c1);
 			GfxFillRect(r.left+10, r.top+3, r.right-10, r.top+3, c2);
 			GfxFillRect(r.left+10, r.top+7, r.right-10, r.top+7, c1);
 			GfxFillRect(r.left+10, r.top+8, r.right-10, r.top+8, c2);
 
-			// draw actual scrollbar
+			/* draw actual scrollbar */
 			pt = HandleScrollbarHittest(&w->hscroll, r.left, r.right);
 			DrawFrameRect(pt.x, r.top, pt.y, r.bottom, wi->color, (w->flags4 & (WF_SCROLL_MIDDLE | WF_HSCROLL)) == (WF_SCROLL_MIDDLE | WF_HSCROLL) ? FR_LOWERED : FR_NONE);
 
@@ -404,19 +406,19 @@ void DrawWindowWidgets(const Window *w)
 			c1 = _colour_gradient[wi->color][3];
 			c2 = _colour_gradient[wi->color][7];
 
-			//Line from upper left corner to start of text
+			/*Line from upper left corner to start of text */
 			GfxFillRect(r.left, r.top+4, r.left+4,r.top+4, c1);
 			GfxFillRect(r.left+1, r.top+5, r.left+4,r.top+5, c2);
 
-			// Line from end of text to upper right corner
+			/* Line from end of text to upper right corner */
 			GfxFillRect(x2, r.top+4, r.right-1,r.top+4,c1);
 			GfxFillRect(x2, r.top+5, r.right-2,r.top+5,c2);
 
-			// Line from upper left corner to bottom left corner
+			/* Line from upper left corner to bottom left corner */
 			GfxFillRect(r.left, r.top+5, r.left, r.bottom-1, c1);
 			GfxFillRect(r.left+1, r.top+6, r.left+1, r.bottom-2, c2);
 
-			//Line from upper right corner to bottom right corner
+			/*Line from upper right corner to bottom right corner */
 			GfxFillRect(r.right-1, r.top+5, r.right-1, r.bottom-2, c1);
 			GfxFillRect(r.right, r.top+4, r.right, r.bottom-1, c2);
 
@@ -501,7 +503,7 @@ static int GetDropdownItem(const Window *w)
 	if (item >= WP(w,dropdown_d).num_items || (HASBIT(WP(w,dropdown_d).disabled_state, item) && !HASBIT(WP(w,dropdown_d).hidden_state, item)) || WP(w,dropdown_d).items[item] == 0)
 		return - 1;
 
-	// Skip hidden items -- +1 for each hidden item before the clicked item.
+	/* Skip hidden items -- +1 for each hidden item before the clicked item. */
 	for (counter = 0; item >= counter; ++counter)
 		if (HASBIT(WP(w,dropdown_d).hidden_state, counter)) item++;
 
diff --git a/src/win32.cpp b/src/win32.cpp
index 45a3489bc..0b48575e0 100644
--- a/src/win32.cpp
+++ b/src/win32.cpp
@@ -84,7 +84,7 @@ void ShowOSErrorBox(const char *buf)
 	MyShowCursor(true);
 	MessageBox(GetActiveWindow(), MB_TO_WIDE(buf), _T("Error!"), MB_ICONSTOP);
 
-// if exception tracker is enabled, we crash here to let the exception handler handle it.
+/* if exception tracker is enabled, we crash here to let the exception handler handle it. */
 #if defined(WIN32_EXCEPTION_TRACKER) && !defined(_DEBUG)
 	if (*buf == '!') {
 		_exception_string = buf;
@@ -747,7 +747,7 @@ void FiosGetDrives()
 
 bool FiosIsValidFile(const char *path, const struct dirent *ent, struct stat *sb)
 {
-	// hectonanoseconds between Windows and POSIX epoch
+	/* hectonanoseconds between Windows and POSIX epoch */
 	static const int64 posix_epoch_hns = 0x019DB1DED53E8000LL;
 	const WIN32_FIND_DATA *fd = &ent->dir->fd;
 
@@ -790,13 +790,13 @@ static int ParseCommandLine(char *line, char **argv, int max_argc)
 	int n = 0;
 
 	do {
-		// skip whitespace
+		/* skip whitespace */
 		while (*line == ' ' || *line == '\t') line++;
 
-		// end?
+		/* end? */
 		if (*line == '\0') break;
 
-		// special handling when quoted
+		/* special handling when quoted */
 		if (*line == '"') {
 			argv[n++] = ++line;
 			while (*line != '"') {
@@ -831,13 +831,13 @@ void CreateConsole()
 	coninfo.dwSize.Y = 500;
 	SetConsoleScreenBufferSize(hand, coninfo.dwSize);
 
-	// redirect unbuffered STDIN, STDOUT, STDERR to the console
+	/* redirect unbuffered STDIN, STDOUT, STDERR to the console */
 #if !defined(__CYGWIN__)
 	*stdout = *_fdopen( _open_osfhandle((intptr_t)hand, _O_TEXT), "w" );
 	*stdin = *_fdopen(_open_osfhandle((intptr_t)GetStdHandle(STD_INPUT_HANDLE), _O_TEXT), "r" );
 	*stderr = *_fdopen(_open_osfhandle((intptr_t)GetStdHandle(STD_ERROR_HANDLE), _O_TEXT), "w" );
 #else
-	// open_osfhandle is not in cygwin
+	/* open_osfhandle is not in cygwin */
 	*stdout = *fdopen(1, "w" );
 	*stdin = *fdopen(0, "r" );
 	*stderr = *fdopen(2, "w" );
@@ -1037,8 +1037,8 @@ void CSleep(int milliseconds)
 }
 
 
-// Utility function to get the current timestamp in milliseconds
-// Useful for profiling
+/** Utility function to get the current timestamp in milliseconds
+ * Useful for profiling */
 int64 GetTS()
 {
 	static double freq;
diff --git a/src/window.cpp b/src/window.cpp
index d38abb4e2..19b1b4cd7 100644
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -18,7 +18,7 @@
 #include "genworld.h"
 #include "helpers.hpp"
 
-// delta between mouse cursor and upper left corner of dragged window
+/* delta between mouse cursor and upper left corner of dragged window */
 static Point _drag_delta;
 
 static Window _windows[25];
@@ -101,7 +101,7 @@ static void DispatchLeftClickEvent(Window *w, int x, int y)
 
 	if (w->desc_flags & WDF_DEF_WIDGET) {
 		e.we.click.widget = GetWidgetFromPos(w, x, y);
-		if (e.we.click.widget < 0) return; /* exit if clicked outside of widgets */
+		if (e.we.click.widget < 0) return; // exit if clicked outside of widgets
 
 		/* don't allow any interaction if the button has been disabled */
 		if (IsWindowWidgetDisabled(w, e.we.click.widget)) return;
@@ -157,7 +157,7 @@ static void DispatchRightClickEvent(Window *w, int x, int y)
 	if (w->desc_flags & WDF_STD_TOOLTIPS) {
 		e.we.click.widget = GetWidgetFromPos(w, x, y);
 		if (e.we.click.widget < 0)
-			return; /* exit if clicked outside of widgets */
+			return; // exit if clicked outside of widgets
 
 		if (w->widget[e.we.click.widget].tooltips != 0) {
 			GuiShowTooltips(w->widget[e.we.click.widget].tooltips);
@@ -596,7 +596,7 @@ static Window *LocalAllocateWindow(
 		DeleteWindow(w);
 	}
 
-	// Set up window properties
+	/* Set up window properties */
 	memset(w, 0, sizeof(*w));
 	w->window_class = cls;
 	w->flags4 = WF_WHITE_BORDER_MASK; // just opened windows have a white border
@@ -685,7 +685,7 @@ static bool IsGoodAutoPlace1(int left, int top)
 	if (left < 0 || top < 22 || right > _screen.width || bottom > _screen.height)
 		return false;
 
-	// Make sure it is not obscured by any window.
+	/* Make sure it is not obscured by any window. */
 	FOR_ALL_WINDOWS(wz) {
 		const Window *w = *wz;
 		if (w->window_class == WC_MAIN_WINDOW) continue;
@@ -714,7 +714,7 @@ static bool IsGoodAutoPlace2(int left, int top)
 	if (left < -(width>>2) || left > _screen.width - (width>>1)) return false;
 	if (top < 22 || top > _screen.height - (height>>2)) return false;
 
-	// Make sure it is not obscured by any window.
+	/* Make sure it is not obscured by any window. */
 	FOR_ALL_WINDOWS(wz) {
 		const Window *w = *wz;
 		if (w->window_class == WC_MAIN_WINDOW) continue;
@@ -936,7 +936,7 @@ static void DecreaseWindowCounters()
 
 	for (wz = _last_z_window; wz != _z_windows;) {
 		w = *--wz;
-		// Unclick scrollbar buttons if they are pressed.
+		/* Unclick scrollbar buttons if they are pressed. */
 		if (w->flags4 & (WF_SCROLL_DOWN | WF_SCROLL_UP)) {
 			w->flags4 &= ~(WF_SCROLL_DOWN | WF_SCROLL_UP);
 			SetWindowDirty(w);
@@ -993,7 +993,7 @@ static bool HandleDragDrop()
 	ResetObjectToPlace();
 
 	if (w != NULL) {
-		// send an event in client coordinates.
+		/* send an event in client coordinates. */
 		e.event = WE_DRAGDROP;
 		e.we.dragdrop.pt.x = _cursor.pos.x - w->left;
 		e.we.dragdrop.pt.y = _cursor.pos.y - w->top;
@@ -1038,7 +1038,7 @@ static bool HandleMouseOver()
 
 	w = FindWindowFromPt(_cursor.pos.x, _cursor.pos.y);
 
-	// We changed window, put a MOUSEOVER event to the last window
+	/* We changed window, put a MOUSEOVER event to the last window */
 	if (last_w != NULL && last_w != w) {
 		e.event = WE_MOUSEOVER;
 		e.we.mouseover.pt.x = -1;
@@ -1048,7 +1048,7 @@ static bool HandleMouseOver()
 	last_w = w;
 
 	if (w != NULL) {
-		// send an event in client coordinates.
+		/* send an event in client coordinates. */
 		e.event = WE_MOUSEOVER;
 		e.we.mouseover.pt.x = _cursor.pos.x - w->left;
 		e.we.mouseover.pt.y = _cursor.pos.y - w->top;
@@ -1058,7 +1058,7 @@ static bool HandleMouseOver()
 		w->wndproc(w, &e);
 	}
 
-	// Mouseover never stops execution
+	/* Mouseover never stops execution */
 	return true;
 }
 
@@ -1117,10 +1117,10 @@ static bool _dragging_window;
 static bool HandleWindowDragging()
 {
 	Window* const *wz;
-	// Get out immediately if no window is being dragged at all.
+	/* Get out immediately if no window is being dragged at all. */
 	if (!_dragging_window) return true;
 
-	// Otherwise find the window...
+	/* Otherwise find the window... */
 	FOR_ALL_WINDOWS(wz) {
 		Window *w = *wz;
 
@@ -1132,7 +1132,7 @@ static bool HandleWindowDragging()
 			int nx;
 			int ny;
 
-			// Stop the dragging if the left mouse button was released
+			/* Stop the dragging if the left mouse button was released */
 			if (!_left_button_down) {
 				w->flags4 &= ~WF_DRAGGING;
 				break;
@@ -1158,14 +1158,14 @@ static bool HandleWindowDragging()
 					if (v == w) continue; // Don't snap at yourself
 
 					if (y + w->height > v->top && y < v->top + v->height) {
-						// Your left border <-> other right border
+						/* Your left border <-> other right border */
 						delta = abs(v->left + v->width - x);
 						if (delta <= hsnap) {
 							nx = v->left + v->width;
 							hsnap = delta;
 						}
 
-						// Your right border <-> other left border
+						/* Your right border <-> other left border */
 						delta = abs(v->left - x - w->width);
 						if (delta <= hsnap) {
 							nx = v->left - w->width;
@@ -1174,14 +1174,14 @@ static bool HandleWindowDragging()
 					}
 
 					if (w->top + w->height >= v->top && w->top <= v->top + v->height) {
-						// Your left border <-> other left border
+						/* Your left border <-> other left border */
 						delta = abs(v->left - x);
 						if (delta <= hsnap) {
 							nx = v->left;
 							hsnap = delta;
 						}
 
-						// Your right border <-> other right border
+						/* Your right border <-> other right border */
 						delta = abs(v->left + v->width - x - w->width);
 						if (delta <= hsnap) {
 							nx = v->left + v->width - w->width;
@@ -1190,14 +1190,14 @@ static bool HandleWindowDragging()
 					}
 
 					if (x + w->width > v->left && x < v->left + v->width) {
-						// Your top border <-> other bottom border
+						/* Your top border <-> other bottom border */
 						delta = abs(v->top + v->height - y);
 						if (delta <= vsnap) {
 							ny = v->top + v->height;
 							vsnap = delta;
 						}
 
-						// Your bottom border <-> other top border
+						/* Your bottom border <-> other top border */
 						delta = abs(v->top - y - w->height);
 						if (delta <= vsnap) {
 							ny = v->top - w->height;
@@ -1206,14 +1206,14 @@ static bool HandleWindowDragging()
 					}
 
 					if (w->left + w->width >= v->left && w->left <= v->left + v->width) {
-						// Your top border <-> other top border
+						/* Your top border <-> other top border */
 						delta = abs(v->top - y);
 						if (delta <= vsnap) {
 							ny = v->top;
 							vsnap = delta;
 						}
 
-						// Your bottom border <-> other bottom border
+						/* Your bottom border <-> other bottom border */
 						delta = abs(v->top + v->height - y - w->height);
 						if (delta <= vsnap) {
 							ny = v->top + v->height - w->height;
@@ -1223,12 +1223,12 @@ static bool HandleWindowDragging()
 				}
 			}
 
-			// Make sure the window doesn't leave the screen
-			// 13 is the height of the title bar
+			/* Make sure the window doesn't leave the screen
+			 * 13 is the height of the title bar */
 			nx = clamp(nx, 13 - t->right, _screen.width - 13 - t->left);
 			ny = clamp(ny, 0, _screen.height - 13);
 
-			// Make sure the title bar isn't hidden by behind the main tool bar
+			/* Make sure the title bar isn't hidden by behind the main tool bar */
 			v = FindWindowById(WC_MAIN_TOOLBAR, 0);
 			if (v != NULL) {
 				int v_bottom = v->top + v->height;
@@ -1345,15 +1345,15 @@ static bool HandleScrollbarScrolling()
 	int pos;
 	Scrollbar *sb;
 
-	// Get out quickly if no item is being scrolled
+	/* Get out quickly if no item is being scrolled */
 	if (!_scrolling_scrollbar) return true;
 
-	// Find the scrolling window
+	/* Find the scrolling window */
 	FOR_ALL_WINDOWS(wz) {
 		Window *w = *wz;
 
 		if (w->flags4 & WF_SCROLL_MIDDLE) {
-			// Abort if no button is clicked any more.
+			/* Abort if no button is clicked any more. */
 			if (!_left_button_down) {
 				w->flags4 &= ~WF_SCROLL_MIDDLE;
 				SetWindowDirty(w);
@@ -1371,7 +1371,7 @@ static bool HandleScrollbarScrolling()
 				i = _cursor.pos.y - _cursorpos_drag_start.y;
 			}
 
-			// Find the item we want to move to and make sure it's inside bounds.
+			/* Find the item we want to move to and make sure it's inside bounds. */
 			pos = min(max(0, i + _scrollbar_start_pos) * sb->count / _scrollbar_size, max(0, sb->count - sb->cap));
 			if (pos != sb->pos) {
 				sb->pos = pos;
@@ -1482,7 +1482,7 @@ static bool MaybeBringWindowToFront(const Window *w)
 }
 
 /** Send a message from one window to another. The receiving window is found by
- * @param w @see Window pointer pointing to the other window
+ * @param w see Window pointer pointing to the other window
  * @param msg Specifies the message to be sent
  * @param wparam Specifies additional message-specific information
  * @param lparam Specifies additional message-specific information
@@ -1500,8 +1500,8 @@ static void SendWindowMessageW(Window *w, uint msg, uint wparam, uint lparam)
 }
 
 /** Send a message from one window to another. The receiving window is found by
- * @param wnd_class @see WindowClass class AND
- * @param wnd_num @see WindowNumber number, mostly 0
+ * @param wnd_class see WindowClass class AND
+ * @param wnd_num see WindowNumber number, mostly 0
  * @param msg Specifies the message to be sent
  * @param wparam Specifies additional message-specific information
  * @param lparam Specifies additional message-specific information
@@ -1514,7 +1514,7 @@ void SendWindowMessage(WindowClass wnd_class, WindowNumber wnd_num, int msg, int
 
 /** Send a message from one window to another. The message will be sent
  * to ALL windows of the windowclass specified in the first parameter
- * @param wnd_class @see WindowClass class
+ * @param wnd_class see WindowClass class
  * @param msg Specifies the message to be sent
  * @param wparam Specifies additional message-specific information
  * @param lparam Specifies additional message-specific information
@@ -1551,13 +1551,13 @@ void HandleKeypress(uint32 key)
 	*/
 	if (!IsGeneratingWorld()) _current_player = _local_player;
 
-	// Setup event
+	/* Setup event */
 	e.event = WE_KEYPRESS;
 	e.we.keypress.key     = GB(key,  0, 16);
 	e.we.keypress.keycode = GB(key, 16, 16);
 	e.we.keypress.cont = true;
 
-	// check if we have a query string window open before allowing hotkeys
+	/* check if we have a query string window open before allowing hotkeys */
 	if (FindWindowById(WC_QUERY_STRING,       0) != NULL ||
 			FindWindowById(WC_SEND_NETWORK_MSG,   0) != NULL ||
 			FindWindowById(WC_GENERATE_LANDSCAPE, 0) != NULL ||
@@ -1566,11 +1566,11 @@ void HandleKeypress(uint32 key)
 		query_open = true;
 	}
 
-	// Call the event, start with the uppermost window.
+	/* Call the event, start with the uppermost window. */
 	for (wz = _last_z_window; wz != _z_windows;) {
 		Window *w = *--wz;
 
-		// if a query window is open, only call the event for certain window types
+		/* if a query window is open, only call the event for certain window types */
 		if (query_open &&
 				w->window_class != WC_QUERY_STRING &&
 				w->window_class != WC_SEND_NETWORK_MSG &&
@@ -1585,7 +1585,7 @@ void HandleKeypress(uint32 key)
 
 	if (e.we.keypress.cont) {
 		Window *w = FindWindowById(WC_MAIN_TOOLBAR, 0);
-		// When there is no toolbar w is null, check for that
+		/* When there is no toolbar w is null, check for that */
 		if (w != NULL) w->wndproc(w, &e);
 	}
 }
@@ -1616,7 +1616,7 @@ static void HandleAutoscroll()
 		if (vp != NULL) {
 			x -= vp->left;
 			y -= vp->top;
-			//here allows scrolling in both x and y axis
+			/* here allows scrolling in both x and y axis */
 #define scrollspeed 3
 			if (x - 15 < 0) {
 				WP(w, vp_d).scrollpos_x += (x - 15) * scrollspeed << vp->zoom;
@@ -1685,7 +1685,7 @@ void MouseLoop(int click, int mousewheel)
 			case 1:
 				DEBUG(misc, 2, "Cursor: 0x%X (%d)", _cursor.sprite, _cursor.sprite);
 				if (_thd.place_mode != 0 &&
-						// query button and place sign button work in pause mode
+						/* query button and place sign button work in pause mode */
 						_cursor.sprite != SPR_CURSOR_QUERY &&
 						_cursor.sprite != SPR_CURSOR_SIGN &&
 						_pause_game != 0 &&
@@ -1736,7 +1736,7 @@ void HandleMouseEvents()
 	 */
 	if (!IsGeneratingWorld()) _current_player = _local_player;
 
-	// Mouse event?
+	/* Mouse event? */
 	click = 0;
 	if (_left_button_down && !_left_button_clicked) {
 		_left_button_clicked = true;
@@ -1793,7 +1793,7 @@ void UpdateWindows()
 		if ((*wz)->viewport != NULL) UpdateViewportPosition(*wz);
 	}
 	DrawTextMessage();
-	// Redraw mouse cursor in case it was hidden
+	/* Redraw mouse cursor in case it was hidden */
 	DrawMouseCursor();
 }
 
diff --git a/src/window.h b/src/window.h
index 7f48d523d..597c6e363 100644
--- a/src/window.h
+++ b/src/window.h
@@ -659,7 +659,7 @@ static inline bool IsWindowWidgetHidden(const Window *w, byte widget_index)
  * Sets the lowered/raised status of a widget.
  * @param w : Window on which the widget is located
  * @param widget_index : index of this widget in the window
- * @param hidden_stat : status to use ie: lowered = true, raised = false
+ * @param lowered_stat : status to use ie: lowered = true, raised = false
  */
 static inline void SetWindowWidgetLoweredState(Window *w, byte widget_index, bool lowered_stat)
 {