(svn r9559) -Documentation: doxygen and comment changes: 'U' and 'V' now. Almost done. Yeah. I know, I've already said that...

12 files changed, 252 insertions, 214 deletions

diff --git a/src/unix.cpp b/src/unix.cpp
index ddcd3aa57..72ac0db12 100644
--- a/src/unix.cpp
+++ b/src/unix.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file unix.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "functions.h"
@@ -27,7 +29,7 @@
 #include <exec/types.h>
 ULONG __stack = (1024*1024)*2; // maybe not that much is needed actually ;)
 
-// The system supplied definition of SIG_IGN does not match
+/* The system supplied definition of SIG_IGN does not match */
 #undef SIG_IGN
 #define SIG_IGN (void (*)(int))1
 #endif /* __MORPHOS__ */
@@ -39,7 +41,7 @@ ULONG __stack = (1024*1024)*2; // maybe not that much is needed actually ;)
 
 #if defined(__APPLE__)
 	#if defined(WITH_SDL)
-		//the mac implementation needs this file included in the same file as main()
+		/*the mac implementation needs this file included in the same file as main() */
 		#include <SDL.h>
 	#endif
 #endif
@@ -104,11 +106,11 @@ void ShowInfo(const char *str)
 void ShowOSErrorBox(const char *buf)
 {
 #if defined(__APPLE__)
-	// this creates an NSAlertPanel with the contents of 'buf'
-	// this is the native and nicest way to do this on OSX
+	/* this creates an NSAlertPanel with the contents of 'buf'
+	 * this is the native and nicest way to do this on OSX */
 	ShowMacDialog( buf, "See readme for more info\nMost likely you are missing files from the original TTD", "Quit" );
 #else
-	// all systems, but OSX
+	/* all systems, but OSX */
 	fprintf(stderr, "\033[1;31mError: %s\033[0;39m\n", buf);
 #endif
 }
@@ -151,10 +153,10 @@ bool InsertTextBufferClipboard(Textbuf *tb)
 }
 
 
-// multi os compatible sleep function
+/* multi os compatible sleep function */
 
 #ifdef __AMIGA__
-// usleep() implementation
+/* usleep() implementation */
 #	include <devices/timer.h>
 #	include <dos/dos.h>
 
@@ -174,7 +176,7 @@ void CSleep(int milliseconds)
 		ULONG signals;
 		ULONG TimerSigBit = 1 << TimerPort->mp_SigBit;
 
-		// send IORequest
+		/* send IORequest */
 		TimerRequest->tr_node.io_Command = TR_ADDREQUEST;
 		TimerRequest->tr_time.tv_secs    = (milliseconds * 1000) / 1000000;
 		TimerRequest->tr_time.tv_micro   = (milliseconds * 1000) % 1000000;
@@ -243,7 +245,7 @@ static const char *convert_tofrom_fs(iconv_t convd, const char *name)
 	}
 
 	*outbuf = '\0';
-	// FIX: invalid characters will abort conversion, but they shouldn't occur?
+	/* FIX: invalid characters will abort conversion, but they shouldn't occur? */
 	return buf;
 }
 
diff --git a/src/unmovable.h b/src/unmovable.h
index d7483aa6e..133f6546f 100644
--- a/src/unmovable.h
+++ b/src/unmovable.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file unmovable.h */
+
 #ifndef UNMOVABLE_H
 #define UNMOVABLE_H
 
diff --git a/src/unmovable_cmd.cpp b/src/unmovable_cmd.cpp
index cbed97cda..23483f159 100644
--- a/src/unmovable_cmd.cpp
+++ b/src/unmovable_cmd.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file unmovable_cmd.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "table/strings.h"
@@ -44,7 +46,7 @@ static int32 DestroyCompanyHQ(PlayerID pid, uint32 flags)
 		InvalidateWindow(WC_COMPANY, pid);
 	}
 
-	// cost of relocating company is 1% of company value
+	/* cost of relocating company is 1% of company value */
 	return CalculateCompanyValue(p) / 100;
 }
 
@@ -69,12 +71,14 @@ void UpdateCompanyHQ(Player *p, uint score)
 	MarkTileDirtyByTile(tile + TileDiffXY(1, 1));
 }
 
+extern int32 CheckFlatLandBelow(TileIndex tile, uint w, uint h, uint flags, uint invalid_dirs, StationID* station);
+
 /** Build or relocate the HQ. This depends if the HQ is already built or not
  * @param tile tile where the HQ will be built or relocated to
+ * @param flags type of operation
  * @param p1 unused
  * @param p2 unused
  */
-extern int32 CheckFlatLandBelow(TileIndex tile, uint w, uint h, uint flags, uint invalid_dirs, StationID* station);
 int32 CmdBuildCompanyHQ(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
 	Player *p = GetPlayer(_current_player);
@@ -87,7 +91,7 @@ int32 CmdBuildCompanyHQ(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	if (CmdFailed(ret)) return ret;
 	cost = ret;
 
-	if (p->location_of_house != 0) { /* Moving HQ */
+	if (p->location_of_house != 0) { // Moving HQ
 		cost += DestroyCompanyHQ(_current_player, flags);
 	}
 
@@ -224,7 +228,7 @@ static int32 ClearTile_Unmovable(TileIndex tile, byte flags)
 		return DoCommand(tile, 0, 0, flags, CMD_SELL_LAND_AREA);
 	}
 
-	// checks if you're allowed to remove unmovable things
+	/* checks if you're allowed to remove unmovable things */
 	if (_game_mode != GM_EDITOR && _current_player != OWNER_WATER && ((flags & DC_AUTO || !_cheats.magic_bulldozer.value)) )
 		return_cmd_error(STR_5800_OBJECT_IN_THE_WAY);
 
@@ -252,14 +256,14 @@ static void GetAcceptedCargo_Unmovable(TileIndex tile, AcceptedCargo ac)
 
 	level = GetCompanyHQSize(tile) + 1;
 
-	// Top town building generates 10, so to make HQ interesting, the top
-	// type makes 20.
+	/* Top town building generates 10, so to make HQ interesting, the top
+	 * type makes 20. */
 	ac[CT_PASSENGERS] = max(1U, level);
 
-	// Top town building generates 4, HQ can make up to 8. The
-	// proportion passengers:mail is different because such a huge
-	// commercial building generates unusually high amount of mail
-	// correspondence per physical visitor.
+	/* Top town building generates 4, HQ can make up to 8. The
+	 * proportion passengers:mail is different because such a huge
+	 * commercial building generates unusually high amount of mail
+	 * correspondence per physical visitor. */
 	ac[CT_MAIL] = max(1U, level / 2);
 }
 
@@ -295,16 +299,16 @@ static void TileLoop_Unmovable(TileIndex tile)
 	assert(level < 6);
 
 	r = Random();
-	// Top town buildings generate 250, so the top HQ type makes 256.
+	/* Top town buildings generate 250, so the top HQ type makes 256. */
 	if (GB(r, 0, 8) < (256 / 4 / (6 - level))) {
 		uint amt = GB(r, 0, 8) / 8 / 4 + 1;
 		if (_economy.fluct <= 0) amt = (amt + 1) >> 1;
 		MoveGoodsToStation(tile, 2, 2, CT_PASSENGERS, amt);
 	}
 
-	// Top town building generates 90, HQ can make up to 196. The
-	// proportion passengers:mail is about the same as in the acceptance
-	// equations.
+	/* Top town building generates 90, HQ can make up to 196. The
+	 * proportion passengers:mail is about the same as in the acceptance
+	 * equations. */
 	if (GB(r, 8, 8) < (196 / 4 / (6 - level))) {
 		uint amt = GB(r, 8, 8) / 8 / 4 + 1;
 		if (_economy.fluct <= 0) amt = (amt + 1) >> 1;
diff --git a/src/unmovable_map.h b/src/unmovable_map.h
index 28c364ff1..256c35717 100644
--- a/src/unmovable_map.h
+++ b/src/unmovable_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file unmovable_map.h */
+
 #ifndef UNMOVABLE_MAP_H
 #define UNMOVABLE_MAP_H
 
diff --git a/src/variables.h b/src/variables.h
index c6c745974..fdbe131fa 100644
--- a/src/variables.h
+++ b/src/variables.h
@@ -1,18 +1,20 @@
 /* $Id$ */
 
+/** @file variables.h */
+
 #ifndef VARIABLES_H
 #define VARIABLES_H
 
 #include "yapf/yapf_settings.h"
 
-// ********* START OF SAVE REGION
+/* ********* START OF SAVE REGION */
 #if !defined(MAX_PATH)
 # define MAX_PATH 260
 #endif
 
 #include "gfx.h"
 
-// Prices and also the fractional part.
+/* Prices and also the fractional part. */
 VARDEF Prices _price;
 VARDEF uint16 _price_frac[NUM_PRICES];
 
@@ -38,47 +40,47 @@ VARDEF GameOptions _opt;
 /* These are the default options for a new game */
 VARDEF GameOptions _opt_newgame;
 
-// Pointer to one of the two _opt OR _opt_newgame structs
+/* Pointer to one of the two _opt OR _opt_newgame structs */
 VARDEF GameOptions *_opt_ptr;
 
-// Amount of game ticks
+/* Amount of game ticks */
 VARDEF uint16 _tick_counter;
 
-// This one is not used anymore.
+/* This one is not used anymore. */
 VARDEF VehicleID _vehicle_id_ctr_day;
 
-// Skip aging of cargo?
+/* Skip aging of cargo? */
 VARDEF byte _age_cargo_skip_counter;
 
-// Position in tile loop
+/* Position in tile loop */
 VARDEF TileIndex _cur_tileloop_tile;
 
-// Also save scrollpos_x, scrollpos_y and zoom
+/* Also save scrollpos_x, scrollpos_y and zoom */
 VARDEF uint16 _disaster_delay;
 
-// Determines what station to operate on in the
-//  tick handler.
+/* Determines what station to operate on in the
+ *  tick handler. */
 VARDEF uint16 _station_tick_ctr;
 
 VARDEF uint32 _random_seeds[2][2];
 
-// Iterator through all towns in OnTick_Town
+/* Iterator through all towns in OnTick_Town */
 VARDEF uint32 _cur_town_ctr;
-// Frequency iterator at the same place
+/* Frequency iterator at the same place */
 VARDEF uint32 _cur_town_iter;
 
 VARDEF uint _cur_player_tick_index;
 VARDEF uint _next_competitor_start;
 
-// Determines how often to run the tree loop
+/* Determines how often to run the tree loop */
 VARDEF byte _trees_tick_ctr;
 
-// Keep track of current game position
+/* Keep track of current game position */
 VARDEF int _saved_scrollpos_x;
 VARDEF int _saved_scrollpos_y;
 VARDEF byte _saved_scrollpos_zoom;
 
-// ********* END OF SAVE REGION
+/* ********* END OF SAVE REGION */
 
 struct Patches {
 	bool modified_catchment;            // different-size catchment areas
@@ -201,22 +203,22 @@ struct Patches {
 	 */
 	uint32 npf_max_search_nodes;
 
-	uint32 npf_rail_firstred_penalty;      /* The penalty for when the first signal is red (and it is not an exit or combo signal) */
-	uint32 npf_rail_firstred_exit_penalty; /* The penalty for when the first signal is red (and it is an exit or combo signal) */
-	uint32 npf_rail_lastred_penalty;       /* The penalty for when the last signal is red */
-	uint32 npf_rail_station_penalty;       /* The penalty for station tiles */
-	uint32 npf_rail_slope_penalty;         /* The penalty for sloping upwards */
-	uint32 npf_rail_curve_penalty;         /* The penalty for curves */
-	uint32 npf_rail_depot_reverse_penalty; /* The penalty for reversing in depots */
-	uint32 npf_buoy_penalty;               /* The penalty for going over (through) a buoy */
-	uint32 npf_water_curve_penalty;        /* The penalty for curves */
-	uint32 npf_road_curve_penalty;         /* The penalty for curves */
-	uint32 npf_crossing_penalty;           /* The penalty for level crossings */
-	uint32 npf_road_drive_through_penalty; /* The penalty for going through a drive-through road stop */
+	uint32 npf_rail_firstred_penalty;      // The penalty for when the first signal is red (and it is not an exit or combo signal)
+	uint32 npf_rail_firstred_exit_penalty; // The penalty for when the first signal is red (and it is an exit or combo signal)
+	uint32 npf_rail_lastred_penalty;       // The penalty for when the last signal is red
+	uint32 npf_rail_station_penalty;       // The penalty for station tiles
+	uint32 npf_rail_slope_penalty;         // The penalty for sloping upwards
+	uint32 npf_rail_curve_penalty;         // The penalty for curves
+	uint32 npf_rail_depot_reverse_penalty; // The penalty for reversing in depots
+	uint32 npf_buoy_penalty;               // The penalty for going over (through) a buoy
+	uint32 npf_water_curve_penalty;        // The penalty for curves
+	uint32 npf_road_curve_penalty;         // The penalty for curves
+	uint32 npf_crossing_penalty;           // The penalty for level crossings
+	uint32 npf_road_drive_through_penalty; // The penalty for going through a drive-through road stop
 
 	bool population_in_label; // Show the population of a town in his label?
 
-	uint8 freight_trains; ///< Value to multiply the weight of cargo by
+	uint8 freight_trains; // Value to multiply the weight of cargo by
 
 	/** YAPF settings */
 	YapfSettings  yapf;
@@ -234,9 +236,9 @@ struct Cheat {
 };
 
 
-// WARNING! Do _not_ remove entries in Cheats struct or change the order
-// of the existing ones! Would break downward compatibility.
-// Only add new entries at the end of the struct!
+/* WARNING! Do _not_ remove entries in Cheats struct or change the order
+ * of the existing ones! Would break downward compatibility.
+ * Only add new entries at the end of the struct! */
 
 struct Cheats {
 	Cheat magic_bulldozer;  // dynamite industries, unmovables
@@ -268,7 +270,7 @@ struct Paths {
 
 VARDEF Paths _paths;
 
-// NOSAVE: Used in palette animations only, not really important.
+/* NOSAVE: Used in palette animations only, not really important. */
 VARDEF int _timer_counter;
 
 
@@ -291,20 +293,20 @@ VARDEF uint32 _decode_parameters[20];
 
 VARDEF bool _rightclick_emulate;
 
-// IN/OUT parameters to commands
+/* IN/OUT parameters to commands */
 VARDEF byte _yearly_expenses_type;
 VARDEF TileIndex _terraform_err_tile;
 VARDEF TileIndex _build_tunnel_endtile;
 VARDEF bool _generating_world;
 
-// Deals with the type of the savegame, independent of extension
+/* Deals with the type of the savegame, independent of extension */
 struct SmallFiosItem {
 	int mode;             // savegame/scenario type (old, new)
 	char name[MAX_PATH];  // name
 	char title[255];      // internal name of the game
 };
 
-// Used when switching from the intro menu.
+/* Used when switching from the intro menu. */
 VARDEF byte _switch_mode;
 VARDEF StringID _switch_mode_errorstr;
 VARDEF SmallFiosItem _file_to_saveload;
@@ -372,14 +374,14 @@ static inline uint32 GetDParam(uint n)
 	return _decode_parameters[n];
 }
 
-// Used to bind a C string name to a dparam number.
-// NOTE: This has a short lifetime. You can't
-//       use this string much later or it will be gone.
+/* Used to bind a C string name to a dparam number.
+ * NOTE: This has a short lifetime. You can't
+ *       use this string much later or it will be gone. */
 void SetDParamStr(uint n, const char *str);
 
-// This function takes a C-string and allocates a temporary string ID.
-// The duration of the bound string is valid only until the next acll to GetString,
-// so be careful.
+/** This function takes a C-string and allocates a temporary string ID.
+ * The duration of the bound string is valid only until the next acll to GetString,
+ * so be careful. */
 StringID BindCString(const char *str);
 
 
@@ -389,7 +391,7 @@ StringID BindCString(const char *str);
 
 #define SET_EXPENSES_TYPE(x) _yearly_expenses_type = x;
 
-/* landscape.c */
+/* landscape.cpp */
 extern const byte _tileh_to_sprite[32];
 extern const Slope _inclined_tileh[16];
 
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index 5e8d64538..870a291f2 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file vehicle.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "road_map.h"
@@ -104,7 +106,7 @@ void VehicleServiceInDepot(Vehicle *v)
 bool VehicleNeedsService(const Vehicle *v)
 {
 	if (v->vehstatus & VS_CRASHED)
-		return false; /* Crashed vehicles don't need service anymore */
+		return false; // Crashed vehicles don't need service anymore
 
 	if (_patches.no_servicing_if_no_breakdowns && _opt.diff.vehicle_breakdowns == 0) {
 		return EngineHasReplacementForPlayer(GetPlayer(v->owner), v->engine_type);  /* Vehicles set for autoreplacing needs to go to a depot even if breakdowns are turned off */
@@ -215,7 +217,7 @@ void VehiclePositionChanged(Vehicle *v)
 	v->bottom_coord = pt.y + spr->height + 2;
 }
 
-// Called after load to update coordinates
+/** Called after load to update coordinates */
 void AfterLoadVehicles()
 {
 	Vehicle *v;
@@ -311,7 +313,7 @@ Vehicle *ForceAllocateSpecialVehicle()
 	return NULL;
 }
 
-/*
+/**
  * finds a free vehicle in the memory or allocates a new one
  * returns a pointer to the first free vehicle or NULL if all vehicles are in use
  * *skip_vehicles is an offset to where in the array we should begin looking
@@ -327,7 +329,7 @@ static Vehicle *AllocateSingleVehicle(VehicleID *skip_vehicles)
 	const int offset = (1 << Vehicle_POOL_BLOCK_SIZE_BITS) * BLOCKS_FOR_SPECIAL_VEHICLES;
 
 	/* We don't use FOR_ALL here, because FOR_ALL skips invalid items.
-	 * TODO - This is just a temporary stage, this will be removed. */
+	 * @todo - This is just a temporary stage, this will be removed. */
 	if (*skip_vehicles < (_Vehicle_pool.total_items - offset)) { // make sure the offset in the array is not larger than the array itself
 		for (v = GetVehicle(offset + *skip_vehicles); v != NULL; v = (v->index + 1U < GetVehiclePoolSize()) ? GetVehicle(v->index + 1) : NULL) {
 			(*skip_vehicles)++;
@@ -381,7 +383,7 @@ void *VehicleFromPos(TileIndex tile, void *data, VehicleFromPosProc *proc)
 {
 	Point pt = RemapCoords(TileX(tile) * TILE_SIZE, TileY(tile) * TILE_SIZE, 0);
 
-	// The hash area to scan
+	/* The hash area to scan */
 	const int xl = GB(pt.x - 174, 7, 6);
 	const int xu = GB(pt.x + 104, 7, 6);
 	const int yl = GB(pt.y - 294, 6, 6) << 6;
@@ -498,7 +500,7 @@ Vehicle *GetPrevVehicleInChain(const Vehicle *v)
 
 	u = GetFirstVehicleInChain(v);
 
-	// Check to see if this is the first
+	/* Check to see if this is the first */
 	if (v == u) return NULL;
 
 	for (; u->next != v; u = u->next) assert(u->next != NULL);
@@ -606,7 +608,7 @@ void Train_Tick(Vehicle *v);
 static void EffectVehicle_Tick(Vehicle *v);
 void DisasterVehicle_Tick(Vehicle *v);
 
-// head of the linked list to tell what vehicles that visited a depot in a tick
+/** head of the linked list to tell what vehicles that visited a depot in a tick */
 static Vehicle* _first_veh_in_depot_list;
 
 /** Adds a vehicle to the list of vehicles, that visited a depot this tick
@@ -614,14 +616,14 @@ static Vehicle* _first_veh_in_depot_list;
  */
 void VehicleEnteredDepotThisTick(Vehicle *v)
 {
-	// we need to set v->leave_depot_instantly as we have no control of it's contents at this time
+	/* we need to set v->leave_depot_instantly as we have no control of it's contents at this time */
 	if (HASBIT(v->current_order.flags, OFB_HALT_IN_DEPOT) && !HASBIT(v->current_order.flags, OFB_PART_OF_ORDERS) && v->current_order.type == OT_GOTO_DEPOT) {
-		// we keep the vehicle in the depot since the user ordered it to stay
+		/* we keep the vehicle in the depot since the user ordered it to stay */
 		v->leave_depot_instantly = false;
 	} else {
-		// the vehicle do not plan on stopping in the depot, so we stop it to ensure that it will not reserve the path
-		// out of the depot before we might autoreplace it to a different engine. The new engine would not own the reserved path
-		// we store that we stopped the vehicle, so autoreplace can start it again
+		/* the vehicle do not plan on stopping in the depot, so we stop it to ensure that it will not reserve the path
+		 * out of the depot before we might autoreplace it to a different engine. The new engine would not own the reserved path
+		 * we store that we stopped the vehicle, so autoreplace can start it again */
 		v->vehstatus |= VS_STOPPED;
 		v->leave_depot_instantly = true;
 	}
@@ -650,8 +652,8 @@ void CallVehicleTicks()
 	Vehicle *v;
 
 #ifdef ENABLE_NETWORK
-	// hotfix for desync problem:
-	//  for MP games invalidate the YAPF cache every tick to keep it exactly the same on the server and all clients
+	/* hotfix for desync problem:
+	 *  for MP games invalidate the YAPF cache every tick to keep it exactly the same on the server and all clients */
 	if (_networking) {
 		YapfNotifyTrackLayoutChange(INVALID_TILE, INVALID_TRACK);
 	}
@@ -679,7 +681,7 @@ void CallVehicleTicks()
 		}
 	}
 
-	// now we handle all the vehicles that entered a depot this tick
+	/* now we handle all the vehicles that entered a depot this tick */
 	v = _first_veh_in_depot_list;
 	while (v != NULL) {
 		Vehicle *w = v->depot_list;
@@ -695,19 +697,19 @@ static bool CanFillVehicle_FullLoadAny(Vehicle *v)
 	bool keep_loading = false;
 	const GoodsEntry *ge = GetStation(v->last_station_visited)->goods;
 
-	//special handling of aircraft
+	/* special handling of aircraft */
 
-	//if the aircraft carries passengers and is NOT full, then
-	//continue loading, no matter how much mail is in
+	/* if the aircraft carries passengers and is NOT full, then
+	 *continue loading, no matter how much mail is in */
 	if (v->type == VEH_AIRCRAFT &&
 			IsCargoInClass(v->cargo_type, CC_PASSENGERS) &&
 			v->cargo_cap != v->cargo_count) {
 		return true;
 	}
 
-	// patch should return "true" to continue loading, i.e. when there is no cargo type that is fully loaded.
+	/* patch should return "true" to continue loading, i.e. when there is no cargo type that is fully loaded. */
 	do {
-		//Should never happen, but just in case future additions change this
+		/* Should never happen, but just in case future additions change this */
 		assert(v->cargo_type<32);
 
 		if (v->cargo_cap != 0) {
@@ -726,7 +728,7 @@ static bool CanFillVehicle_FullLoadAny(Vehicle *v)
 		}
 	} while ((v = v->next) != NULL);
 
-	// continue loading if there is a non full cargo type and no cargo type that is full
+	/* continue loading if there is a non full cargo type and no cargo type that is full */
 	return keep_loading || (not_full && (full & ~not_full) == 0);
 }
 
@@ -743,7 +745,7 @@ bool CanFillVehicle(Vehicle *v)
 				IsTileType(TILE_ADDXY(tile, -2,  0), MP_STATION)
 			))) {
 
-		// If patch is active, use alternative CanFillVehicle-function
+		/* If patch is active, use alternative CanFillVehicle-function */
 		if (_patches.full_load_any && v->current_order.flags & OF_FULL_LOAD) return CanFillVehicle_FullLoadAny(v);
 
 		do {
@@ -821,13 +823,13 @@ static void DoDrawVehicle(const Vehicle *v)
 
 void ViewportAddVehicles(DrawPixelInfo *dpi)
 {
-	// The bounding rectangle
+	/* The bounding rectangle */
 	const int l = dpi->left;
 	const int r = dpi->left + dpi->width;
 	const int t = dpi->top;
 	const int b = dpi->top + dpi->height;
 
-	// The hash area to scan
+	/* The hash area to scan */
 	const int xl = GB(l - 70, 7, 6);
 	const int xu = GB(r,      7, 6);
 	const int yl = GB(t - 70, 6, 6) << 6;
@@ -1567,7 +1569,7 @@ static void ShowVehicleGettingOld(Vehicle *v, StringID msg)
 {
 	if (v->owner != _local_player) return;
 
-	// Do not show getting-old message if autorenew is active
+	/* Do not show getting-old message if autorenew is active */
 	if (GetPlayer(v->owner)->engine_renew) return;
 
 	SetDParam(0, _vehicle_type_names[v->type]);
@@ -1599,6 +1601,7 @@ void AgeVehicle(Vehicle *v)
 
 /** Starts or stops a lot of vehicles
  * @param tile Tile of the depot where the vehicles are started/stopped (only used for depots)
+ * @param flags type of operation
  * @param p1 Station/Order/Depot ID (only used for vehicle list windows)
  * @param p2 bitmask
  *   - bit 0-4 Vehicle type
@@ -1665,10 +1668,11 @@ int32 CmdMassStartStopVehicle(TileIndex tile, uint32 flags, uint32 p1, uint32 p2
 }
 
 /** Sells all vehicles in a depot
-* @param tile Tile of the depot where the depot is
-* @param p1 Vehicle type
-* @param p2 unused
-*/
+ * @param tile Tile of the depot where the depot is
+ * @param flags type of operation
+ * @param p1 Vehicle type
+ * @param p2 unused
+ */
 int32 CmdDepotSellAllVehicles(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
 	Vehicle **engines = NULL;
@@ -1717,10 +1721,11 @@ int32 CmdDepotSellAllVehicles(TileIndex tile, uint32 flags, uint32 p1, uint32 p2
 }
 
 /** Autoreplace all vehicles in the depot
-* @param tile Tile of the depot where the vehicles are
-* @param p1 Type of vehicle
-* @param p2 Unused
-*/
+ * @param tile Tile of the depot where the vehicles are
+ * @param flags type of operation
+ * @param p1 Type of vehicle
+ * @param p2 Unused
+ */
 int32 CmdDepotMassAutoReplace(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 {
 	Vehicle **vl = NULL;
@@ -1784,6 +1789,7 @@ int32 CmdDepotMassAutoReplace(TileIndex tile, uint32 flags, uint32 p1, uint32 p2
 
 /** Clone a vehicle. If it is a train, it will clone all the cars too
  * @param tile tile of the depot where the cloned vehicle is build
+ * @param flags type of operation
  * @param p1 the original vehicle's index
  * @param p2 1 = shared orders, else copied orders
  */
@@ -1814,7 +1820,7 @@ int32 CmdCloneVehicle(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 	if (v->type == VEH_TRAIN && (!IsFrontEngine(v) || v->u.rail.crash_anim_pos >= 4400)) return CMD_ERROR;
 
-	// check that we can allocate enough vehicles
+	/* check that we can allocate enough vehicles */
 	if (!(flags & DC_EXEC)) {
 		int veh_counter = 0;
 		do {
@@ -1862,11 +1868,11 @@ int32 CmdCloneVehicle(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 			}
 
 			if (v->type == VEH_TRAIN && !IsFrontEngine(v)) {
-				// this s a train car
-				// add this unit to the end of the train
+				/* this s a train car
+				 * add this unit to the end of the train */
 				DoCommand(0, (w_rear->index << 16) | w->index, 1, flags, CMD_MOVE_RAIL_VEHICLE);
 			} else {
-				// this is a front engine or not a train. It need orders
+				/* this is a front engine or not a train. It need orders */
 				w_front = w;
 				w->service_interval = v->service_interval;
 				DoCommand(0, (v->index << 16) | w->index, p2 & 1 ? CO_SHARE : CO_COPY, flags, CMD_CLONE_ORDER);
@@ -1876,7 +1882,7 @@ int32 CmdCloneVehicle(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 	} while (v->type == VEH_TRAIN && (v = GetNextVehicle(v)) != NULL);
 
 	if (flags & DC_EXEC && v_front->type == VEH_TRAIN) {
-		// for trains this needs to be the front engine due to the callback function
+		/* for trains this needs to be the front engine due to the callback function */
 		_new_vehicle_id = w_front->index;
 	}
 
@@ -2220,6 +2226,7 @@ void VehicleEnterDepot(Vehicle *v)
 
 /** Give a custom name to your vehicle
  * @param tile unused
+ * @param flags type of operation
  * @param p1 vehicle ID to name
  * @param p2 unused
  */
@@ -2253,6 +2260,7 @@ int32 CmdNameVehicle(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Change the service interval of a vehicle
  * @param tile unused
+ * @param flags type of operation
  * @param p1 vehicle ID that is being service-interval-changed
  * @param p2 new service interval
  */
@@ -2349,27 +2357,27 @@ Trackdir GetVehicleTrackdir(const Vehicle* v)
 
 	switch (v->type) {
 		case VEH_TRAIN:
-			if (v->u.rail.track == TRACK_BIT_DEPOT) /* We'll assume the train is facing outwards */
-				return DiagdirToDiagTrackdir(GetRailDepotDirection(v->tile)); /* Train in depot */
+			if (v->u.rail.track == TRACK_BIT_DEPOT) // We'll assume the train is facing outwards
+				return DiagdirToDiagTrackdir(GetRailDepotDirection(v->tile)); // Train in depot
 
-			if (v->u.rail.track == TRACK_BIT_WORMHOLE) /* train in tunnel, so just use his direction and assume a diagonal track */
+			if (v->u.rail.track == TRACK_BIT_WORMHOLE) // train in tunnel, so just use his direction and assume a diagonal track
 				return DiagdirToDiagTrackdir(DirToDiagDir(v->direction));
 
 			return TrackDirectionToTrackdir(FindFirstTrack(v->u.rail.track), v->direction);
 
 		case VEH_SHIP:
 			if (IsShipInDepot(v))
-				/* We'll assume the ship is facing outwards */
+				// We'll assume the ship is facing outwards
 				return DiagdirToDiagTrackdir(GetShipDepotDirection(v->tile));
 
 			return TrackDirectionToTrackdir(FindFirstTrack(v->u.ship.state), v->direction);
 
 		case VEH_ROAD:
-			if (IsRoadVehInDepot(v)) /* We'll assume the road vehicle is facing outwards */
+			if (IsRoadVehInDepot(v)) // We'll assume the road vehicle is facing outwards
 				return DiagdirToDiagTrackdir(GetRoadDepotDirection(v->tile));
 
-			if (IsStandardRoadStopTile(v->tile)) /* We'll assume the road vehicle is facing outwards */
-				return DiagdirToDiagTrackdir(GetRoadStopDir(v->tile)); /* Road vehicle in a station */
+			if (IsStandardRoadStopTile(v->tile)) // We'll assume the road vehicle is facing outwards
+				return DiagdirToDiagTrackdir(GetRoadStopDir(v->tile)); // Road vehicle in a station
 
 			if (IsDriveThroughStopTile(v->tile)) return DiagdirToDiagTrackdir(DirToDiagDir(v->direction));
 
@@ -2422,16 +2430,16 @@ UnitID GetFreeUnitNumber(byte type)
 		cache = MallocT<bool>(max + 1);
 	}
 
-	// Clear the cache
+	/* Clear the cache */
 	memset(cache, 0, (max + 1) * sizeof(*cache));
 
-	// Fill the cache
+	/* Fill the cache */
 	FOR_ALL_VEHICLES(u) {
 		if (u->type == type && u->owner == _current_player && u->unitnumber != 0 && u->unitnumber <= max)
 			cache[u->unitnumber] = true;
 	}
 
-	// Find the first unused unit number
+	/* Find the first unused unit number */
 	for (unit = 1; unit <= max; unit++) {
 		if (!cache[unit]) break;
 	}
@@ -2562,7 +2570,7 @@ SpriteID GetVehiclePalette(const Vehicle *v)
 	return GetEngineColourMap(v->engine_type, v->owner, INVALID_ENGINE, v);
 }
 
-// Save and load of vehicles
+/** Save and load of vehicles */
 extern const SaveLoad _common_veh_desc[] = {
 	    SLE_VAR(Vehicle, subtype,              SLE_UINT8),
 
@@ -2667,7 +2675,7 @@ extern const SaveLoad _common_veh_desc[] = {
 	    SLE_REF(Vehicle, next_shared,          REF_VEHICLE),
 	    SLE_REF(Vehicle, prev_shared,          REF_VEHICLE),
 
-	// reserve extra space in savegame here. (currently 10 bytes)
+	/* reserve extra space in savegame here. (currently 10 bytes) */
 	SLE_CONDNULL(10,                                                       2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2686,7 +2694,7 @@ static const SaveLoad _train_desc[] = {
 	SLE_CONDVARX(offsetof(Vehicle, u) + offsetof(VehicleRail, days_since_order_progr), SLE_UINT16, 2, SL_MAX_VERSION),
 
 	SLE_CONDNULL(2, 2, 19),
-	// reserve extra space in savegame here. (currently 11 bytes)
+	/* reserve extra space in savegame here. (currently 11 bytes) */
 	SLE_CONDNULL(11, 2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2706,7 +2714,7 @@ static const SaveLoad _roadveh_desc[] = {
 	SLE_CONDREFX(offsetof(Vehicle, u) + offsetof(VehicleRoad, slot),     REF_ROADSTOPS, 6, SL_MAX_VERSION),
 	SLE_CONDNULL(1,                                                                     6, SL_MAX_VERSION),
 	SLE_CONDVARX(offsetof(Vehicle, u) + offsetof(VehicleRoad, slot_age), SLE_UINT8,     6, SL_MAX_VERSION),
-	// reserve extra space in savegame here. (currently 16 bytes)
+	/* reserve extra space in savegame here. (currently 16 bytes) */
 	SLE_CONDNULL(16,                                                                    2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2717,7 +2725,7 @@ static const SaveLoad _ship_desc[] = {
 	SLE_INCLUDEX(0, INC_VEHICLE_COMMON),
 	SLE_VARX(offsetof(Vehicle, u) + offsetof(VehicleShip, state), SLE_UINT8),
 
-	// reserve extra space in savegame here. (currently 16 bytes)
+	/* reserve extra space in savegame here. (currently 16 bytes) */
 	SLE_CONDNULL(16, 2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2736,7 +2744,7 @@ static const SaveLoad _aircraft_desc[] = {
 
 	SLE_CONDVARX(offsetof(Vehicle, u) + offsetof(VehicleAir, previous_pos),    SLE_UINT8,                 2, SL_MAX_VERSION),
 
-	// reserve extra space in savegame here. (currently 15 bytes)
+	/* reserve extra space in savegame here. (currently 15 bytes) */
 	SLE_CONDNULL(15,                                                                                      2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2768,7 +2776,7 @@ static const SaveLoad _special_desc[] = {
 	    SLE_VARX(offsetof(Vehicle, u) + offsetof(VehicleSpecial, unk0), SLE_UINT16),
 	    SLE_VARX(offsetof(Vehicle, u) + offsetof(VehicleSpecial, unk2), SLE_UINT8),
 
-	// reserve extra space in savegame here. (currently 16 bytes)
+	/* reserve extra space in savegame here. (currently 16 bytes) */
 	SLE_CONDNULL(16, 2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2810,7 +2818,7 @@ static const SaveLoad _disaster_desc[] = {
 	   SLE_VARX(offsetof(Vehicle, u) + offsetof(VehicleDisaster, image_override), SLE_UINT16),
 	   SLE_VARX(offsetof(Vehicle, u) + offsetof(VehicleDisaster, unk2),           SLE_UINT16),
 
-	// reserve extra space in savegame here. (currently 16 bytes)
+	/* reserve extra space in savegame here. (currently 16 bytes) */
 	SLE_CONDNULL(16,                                                 2, SL_MAX_VERSION),
 
 	SLE_END()
@@ -2826,18 +2834,18 @@ static const void *_veh_descs[] = {
 	_disaster_desc,
 };
 
-// Will be called when the vehicles need to be saved.
+/** Will be called when the vehicles need to be saved. */
 static void Save_VEHS()
 {
 	Vehicle *v;
-	// Write the vehicles
+	/* Write the vehicles */
 	FOR_ALL_VEHICLES(v) {
 		SlSetArrayIndex(v->index);
 		SlObject(v, (SaveLoad*)_veh_descs[v->type]);
 	}
 }
 
-// Will be called when vehicles need to be loaded.
+/** Will be called when vehicles need to be loaded. */
 static void Load_VEHS()
 {
 	int index;
diff --git a/src/vehicle.h b/src/vehicle.h
index ff12a139c..8757b14f9 100644
--- a/src/vehicle.h
+++ b/src/vehicle.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @vehicle.h */
+
 #ifndef VEHICLE_H
 #define VEHICLE_H
 
@@ -108,13 +110,13 @@ struct VehicleRail {
 	uint16 crash_anim_pos;
 	uint16 days_since_order_progr;
 
-	// cached values, recalculated on load and each time a vehicle is added to/removed from the consist.
+	/* cached values, recalculated on load and each time a vehicle is added to/removed from the consist. */
 	uint16 cached_max_speed;  // max speed of the consist. (minimum of the max speed of all vehicles in the consist)
 	uint32 cached_power;      // total power of the consist.
 	uint8 cached_veh_length;  // length of this vehicle in units of 1/8 of normal length, cached because this can be set by a callback
 	uint16 cached_total_length; ///< Length of the whole train, valid only for first engine.
 
-	// cached values, recalculated when the cargo on a train changes (in addition to the conditions above)
+	/* cached values, recalculated when the cargo on a train changes (in addition to the conditions above) */
 	uint32 cached_weight;     // total weight of the consist.
 	uint32 cached_veh_weight; // weight of the vehicle.
 	uint32 cached_max_te;     // max tractive effort of consist
@@ -127,8 +129,8 @@ struct VehicleRail {
 	 */
 	byte cached_vis_effect;
 
-	// NOSAVE: for wagon override - id of the first engine in train
-	// 0xffff == not in train
+	/* NOSAVE: for wagon override - id of the first engine in train
+	 * 0xffff == not in train */
 	EngineID first_engine;
 
 	TrackBitsByte track;
@@ -138,27 +140,27 @@ struct VehicleRail {
 
 	byte flags;
 
-	// Link between the two ends of a multiheaded engine
+	/* Link between the two ends of a multiheaded engine */
 	Vehicle *other_multiheaded_part;
 };
 
 enum {
 	VRF_REVERSING         = 0,
 
-	// used to calculate if train is going up or down
+	/* used to calculate if train is going up or down */
 	VRF_GOINGUP           = 1,
 	VRF_GOINGDOWN         = 2,
 
-	// used to store if a wagon is powered or not
+	/* used to store if a wagon is powered or not */
 	VRF_POWEREDWAGON      = 3,
 
-	// used to reverse the visible direction of the vehicle
+	/* used to reverse the visible direction of the vehicle */
 	VRF_REVERSE_DIRECTION = 4,
 
-	// used to mark train as lost because PF can't find the route
+	/* used to mark train as lost because PF can't find the route */
 	VRF_NO_PATH_TO_DESTINATION = 5,
 
-	// used to mark that electric train engine is allowed to run on normal rail
+	/* used to mark that electric train engine is allowed to run on normal rail */
 	VRF_EL_ENGINE_ALLOWED_NORMAL_RAIL = 6,
 };
 
@@ -171,7 +173,7 @@ struct VehicleAir {
 };
 
 struct VehicleRoad {
-	byte state;             /// @see RoadVehicleStates
+	byte state;             ///< @see RoadVehicleStates
 	byte frame;
 	uint16 blocked_ctr;
 	byte overtaking;
@@ -210,7 +212,7 @@ struct Vehicle {
 	StringID string_id;      // Displayed string
 
 	UnitID unitnumber;       // unit number, for display purposes only
-	PlayerByte owner;          // which player owns the vehicle?
+	PlayerByte owner;        // which player owns the vehicle?
 
 	TileIndex tile;          // Current tile index
 	TileIndex dest_tile;     // Heading for this tile
@@ -231,9 +233,9 @@ struct Vehicle {
 	int8 y_offs;             // y offset for vehicle sprite
 	EngineID engine_type;
 
-	// for randomized variational spritegroups
-	// bitmask used to resolve them; parts of it get reseeded when triggers
-	// of corresponding spritegroups get matched
+	/* for randomized variational spritegroups
+	 * bitmask used to resolve them; parts of it get reseeded when triggers
+	 * of corresponding spritegroups get matched */
 	byte random_bits;
 	byte waiting_triggers;   // triggers to be yet matched
 
@@ -269,15 +271,15 @@ struct Vehicle {
 	Vehicle *prev_shared;    ///< If not NULL, this points to the prev vehicle that shared the order
 	/* End Order-stuff */
 
-	// Boundaries for the current position in the world and a next hash link.
-	// NOSAVE: All of those can be updated with VehiclePositionChanged()
+	/* Boundaries for the current position in the world and a next hash link.
+	 * NOSAVE: All of those can be updated with VehiclePositionChanged() */
 	int32 left_coord;
 	int32 top_coord;
 	int32 right_coord;
 	int32 bottom_coord;
 	Vehicle *next_hash;
 
-	// Related to age and service time
+	/* Related to age and service time */
 	Date age;     // Age in days
 	Date max_age; // Maximum age
 	Date date_of_last_service;
@@ -492,7 +494,7 @@ static inline bool IsPlayerBuildableVehicleType(const Vehicle *v)
 
 /**
  * Check if an index is a vehicle-index (so between 0 and max-vehicles)
- *
+ * @param index of the vehicle to query
  * @return Returns true if the vehicle-id is in range
  */
 static inline bool IsValidVehicleID(uint index)
@@ -513,7 +515,11 @@ static inline Order *GetVehicleOrder(const Vehicle *v, int index)
 	return order;
 }
 
-/* Returns the last order of a vehicle, or NULL if it doesn't exists */
+/**
+ * Returns the last order of a vehicle, or NULL if it doesn't exists
+ * @param v Vehicle to query
+ * @return last order of a vehicle, if available
+ */
 static inline Order *GetLastVehicleOrder(const Vehicle *v)
 {
 	Order *order = v->orders;
@@ -526,7 +532,10 @@ static inline Order *GetLastVehicleOrder(const Vehicle *v)
 	return order;
 }
 
-/* Get the first vehicle of a shared-list, so we only have to walk forwards */
+/** Get the first vehicle of a shared-list, so we only have to walk forwards
+ * @param v Vehicle to query
+ * @return first vehicle of a shared-list
+ */
 static inline Vehicle *GetFirstVehicleFromSharedList(const Vehicle *v)
 {
 	Vehicle *u = (Vehicle *)v;
@@ -535,7 +544,7 @@ static inline Vehicle *GetFirstVehicleFromSharedList(const Vehicle *v)
 	return u;
 }
 
-// NOSAVE: Return values from various commands.
+/* NOSAVE: Return values from various commands. */
 VARDEF VehicleID _new_vehicle_id;
 VARDEF uint16 _returned_refit_capacity;
 
diff --git a/src/vehicle_gui.cpp b/src/vehicle_gui.cpp
index 14c5583e5..d04f6fca0 100644
--- a/src/vehicle_gui.cpp
+++ b/src/vehicle_gui.cpp
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file vehicle_gui.cpp */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "debug.h"
@@ -162,12 +164,12 @@ void DepotSortList(Vehicle **v, uint16 length)
 	qsort((void*)v, length, sizeof(v[0]), _vehicle_sorter[0]);
 }
 
-// draw the vehicle profit button in the vehicle list window.
+/** draw the vehicle profit button in the vehicle list window. */
 void DrawVehicleProfitButton(const Vehicle *v, int x, int y)
 {
 	SpriteID pal;
 
-	// draw profit-based colored icons
+	/* draw profit-based colored icons */
 	if (v->age <= 365 * 2) {
 		pal = PALETTE_TO_GREY;
 	} else if (v->profit_last_year < 0) {
@@ -421,6 +423,7 @@ static const WindowDesc _vehicle_refit_desc = {
 
 /** Show the refit window for a vehicle
 * @param *v The vehicle to show the refit window for
+* @param order of the vehicle (?)
 */
 void ShowVehicleRefitWindow(const Vehicle *v, VehicleOrderID order)
 {
@@ -466,18 +469,18 @@ void ShowVehicleRefitWindow(const Vehicle *v, VehicleOrderID order)
 	}
 }
 
-/* Display additional text from NewGRF in the purchase information window */
+/** Display additional text from NewGRF in the purchase information window */
 uint ShowAdditionalText(int x, int y, uint w, EngineID engine)
 {
 	uint16 callback = GetVehicleCallback(CBID_VEHICLE_ADDITIONAL_TEXT, 0, 0, engine, NULL);
 	if (callback == CALLBACK_FAILED) return 0;
 
-	// STR_02BD is used to start the string with {BLACK}
+	/* STR_02BD is used to start the string with {BLACK} */
 	SetDParam(0, GetGRFStringID(GetEngineGRFID(engine), 0xD000 + callback));
 	return DrawStringMultiLine(x, y, STR_02BD, w);
 }
 
-/* Count the number of bits that are set in a mask */
+/** Count the number of bits that are set in a mask */
 static uint CountBits(uint32 mask)
 {
 	uint c = 0;
@@ -485,7 +488,7 @@ static uint CountBits(uint32 mask)
 	return c;
 }
 
-/* Display list of cargo types of the engine, for the purchase information window */
+/** Display list of cargo types of the engine, for the purchase information window */
 uint ShowRefitOptionsList(int x, int y, uint w, EngineID engine)
 {
 	/* List of cargo types of this engine */
@@ -529,7 +532,7 @@ uint ShowRefitOptionsList(int x, int y, uint w, EngineID engine)
 }
 
 
-// if the sorting criteria had the same value, sort vehicle by unitnumber
+/* if the sorting criteria had the same value, sort vehicle by unitnumber */
 #define VEHICLEUNITNUMBERSORTER(r, a, b) {if (r == 0) {r = a->unitnumber - b->unitnumber;}}
 
 static int CDECL VehicleNumberSorter(const void *a, const void *b)
@@ -1140,7 +1143,7 @@ void PlayerVehWndProc(Window *w, WindowEvent *e)
 			switch (e->we.dropdown.button) {
 				case VLW_WIDGET_SORT_BY_PULLDOWN:
 					if (vl->l.sort_type != e->we.dropdown.index) {
-						// value has changed -> resort
+						/* value has changed -> resort */
 						vl->l.flags |= VL_RESORT;
 						vl->l.sort_type = e->we.dropdown.index;
 						vl->_sorting->criteria = vl->l.sort_type;
diff --git a/src/vehicle_gui.h b/src/vehicle_gui.h
index 052bcf110..602d765c0 100644
--- a/src/vehicle_gui.h
+++ b/src/vehicle_gui.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file vehicle_gui.h */
+
 #ifndef VEHICLE_GUI_H
 #define VEHICLE_GUI_H
 
diff --git a/src/viewport.cpp b/src/viewport.cpp
index ab3e087b4..5c7a166c9 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -25,7 +25,7 @@
 
 #define VIEWPORT_DRAW_MEM (65536 * 2)
 
-// XXX - maximum viewports is maximum windows - 2 (main toolbar + status bar)
+/* XXX - maximum viewports is maximum windows - 2 (main toolbar + status bar) */
 static ViewPort _viewports[25 - 2];
 static uint32 _active_viewports;    ///< bitmasked variable where each bit signifies if a viewport is in use or not
 assert_compile(lengthof(_viewports) < sizeof(_active_viewports) * 8);
@@ -91,8 +91,8 @@ struct ParentSpriteToDraw {
 	byte zmax;
 };
 
-// Quick hack to know how much memory to reserve when allocating from the spritelist
-// to prevent a buffer overflow.
+/* Quick hack to know how much memory to reserve when allocating from the spritelist
+ * to prevent a buffer overflow. */
 #define LARGEST_SPRITELIST_STRUCT ParentSpriteToDraw
 
 struct ViewportDrawer {
@@ -438,7 +438,7 @@ void DrawGroundSpriteAt(SpriteID image, SpriteID pal, int32 x, int32 y, byte z)
 void DrawGroundSprite(SpriteID image, SpriteID pal)
 {
 	if (_offset_ground_sprites) {
-		// offset ground sprite because of foundation?
+		/* offset ground sprite because of foundation? */
 		AddChildSpriteScreen(image, pal, _cur_vd->offs_x, _cur_vd->offs_y);
 	} else {
 		_added_tile_sprite = true;
@@ -493,12 +493,12 @@ void AddSortableSpriteToDraw(SpriteID image, SpriteID pal, int x, int y, int w,
 	ps = (ParentSpriteToDraw*)vd->spritelist_mem;
 
 	if (vd->parent_list >= vd->eof_parent_list) {
-		// This can happen rarely, mostly when you zoom out completely
-		//  and have a lot of stuff that moves (and is added to the
-		//  sort-list, this function). To solve it, increase
-		//  parent_list somewhere below to a higher number.
-		// This can not really hurt you, it just gives some black
-		//  spots on the screen ;)
+		/* This can happen rarely, mostly when you zoom out completely
+		 *  and have a lot of stuff that moves (and is added to the
+		 *  sort-list, this function). To solve it, increase
+		 *  parent_list somewhere below to a higher number.
+		 * This can not really hurt you, it just gives some black
+		 *  spots on the screen ;) */
 		DEBUG(sprite, 0, "Out of sprite memory (parent_list)");
 		return;
 	}
@@ -646,23 +646,23 @@ static void DrawTileSelection(const TileInfo *ti)
 	SpriteID image;
 	SpriteID pal;
 
-	// Draw a red error square?
+	/* Draw a red error square? */
 	if (_thd.redsq != 0 && _thd.redsq == ti->tile) {
 		DrawSelectionSprite(SPR_SELECT_TILE + _tileh_to_sprite[ti->tileh], PALETTE_TILE_RED_PULSATING, ti);
 		return;
 	}
 
-	// no selection active?
+	/* no selection active? */
 	if (_thd.drawstyle == 0) return;
 
-	// Inside the inner area?
+	/* Inside the inner area? */
 	if (IS_INSIDE_1D(ti->x, _thd.pos.x, _thd.size.x) &&
 			IS_INSIDE_1D(ti->y, _thd.pos.y, _thd.size.y)) {
 		if (_thd.drawstyle & HT_RECT) {
 			image = SPR_SELECT_TILE + _tileh_to_sprite[ti->tileh];
 			DrawSelectionSprite(image, _thd.make_square_red ? PALETTE_SEL_TILE_RED : PAL_NONE, ti);
 		} else if (_thd.drawstyle & HT_POINT) {
-			// Figure out the Z coordinate for the single dot.
+			/* Figure out the Z coordinate for the single dot. */
 			byte z = ti->z;
 			if (ti->tileh & SLOPE_N) {
 				z += TILE_HEIGHT;
@@ -670,7 +670,7 @@ static void DrawTileSelection(const TileInfo *ti)
 			}
 			DrawGroundSpriteAt(_cur_dpi->zoom != 2 ? SPR_DOT : SPR_DOT_SMALL, PAL_NONE, ti->x, ti->y, z);
 		} else if (_thd.drawstyle & HT_RAIL /*&& _thd.place_mode == VHM_RAIL*/) {
-			// autorail highlight piece under cursor
+			/* autorail highlight piece under cursor */
 			uint type = _thd.drawstyle & 0xF;
 			int offset;
 
@@ -688,7 +688,7 @@ static void DrawTileSelection(const TileInfo *ti)
 			DrawSelectionSprite(image, _thd.make_square_red ? PALETTE_SEL_TILE_RED : pal, ti);
 
 		} else if (IsPartOfAutoLine(ti->x, ti->y)) {
-			// autorail highlighting long line
+			/* autorail highlighting long line */
 			int dir = _thd.drawstyle & ~0xF0;
 			int offset;
 			uint side;
@@ -714,12 +714,12 @@ static void DrawTileSelection(const TileInfo *ti)
 		return;
 	}
 
-	// Check if it's inside the outer area?
+	/* Check if it's inside the outer area? */
 	if (_thd.outersize.x &&
 			_thd.size.x < _thd.size.x + _thd.outersize.x &&
 			IS_INSIDE_1D(ti->x, _thd.pos.x + _thd.offs.x, _thd.size.x + _thd.outersize.x) &&
 			IS_INSIDE_1D(ti->y, _thd.pos.y + _thd.offs.y, _thd.size.y + _thd.outersize.y)) {
-		// Draw a blue rect.
+		/* Draw a blue rect. */
 		DrawSelectionSprite(SPR_SELECT_TILE + _tileh_to_sprite[ti->tileh], PALETTE_SEL_TILE_BLUE, ti);
 		return;
 	}
@@ -734,11 +734,11 @@ static void ViewportAddLandscape()
 
 	_cur_ti = &ti;
 
-	// Transform into tile coordinates and round to closest full tile
+	/* Transform into tile coordinates and round to closest full tile */
 	x = ((vd->dpi.top >> 1) - (vd->dpi.left >> 2)) & ~0xF;
 	y = ((vd->dpi.top >> 1) + (vd->dpi.left >> 2) - 0x10) & ~0xF;
 
-	// determine size of area
+	/* determine size of area */
 	{
 		Point pt = RemapCoords(x, y, 241);
 		width = (vd->dpi.left + vd->dpi.width - pt.x + 95) >> 6;
@@ -1128,7 +1128,7 @@ static void ViewportSortParentSprites(ParentSpriteToDraw *psd[])
 					}
 				}
 
-				// Swap the two sprites ps and ps2 using bubble-sort algorithm.
+				/* Swap the two sprites ps and ps2 using bubble-sort algorithm. */
 				psd3 = psd;
 				do {
 					ParentSpriteToDraw* temp = *psd3;
@@ -1273,8 +1273,8 @@ void ViewportDoDraw(const ViewPort *vp, int left, int top, int right, int bottom
 	ViewportAddSigns(&vd.dpi);
 	ViewportAddWaypoints(&vd.dpi);
 
-	// This assert should never happen (because the length of the parent_list
-	//  is checked)
+	/* This assert should never happen (because the length of the parent_list
+	 *  is checked) */
 	assert(vd.parent_list <= endof(parent_list));
 
 	if (vd.first_tile != NULL) ViewportDrawTileSprites(vd.first_tile);
@@ -1290,8 +1290,8 @@ void ViewportDoDraw(const ViewPort *vp, int left, int top, int right, int bottom
 	_cur_dpi = old_dpi;
 }
 
-// Make sure we don't draw a too big area at a time.
-// If we do, the sprite memory will overflow.
+/** Make sure we don't draw a too big area at a time.
+ * If we do, the sprite memory will overflow. */
 static void ViewportDrawChk(const ViewPort *vp, int left, int top, int right, int bottom)
 {
 	if (((bottom - top) * (right - left) << (2 * vp->zoom)) > 180000) {
@@ -1359,20 +1359,20 @@ void UpdateViewportPosition(Window *w)
 		int vx;
 		int vy;
 
-		// Center of the viewport is hot spot
+		/* Center of the viewport is hot spot */
 		x = WP(w,vp_d).scrollpos_x + vp->virtual_width / 2;
 		y = WP(w,vp_d).scrollpos_y + vp->virtual_height / 2;
-		// Convert viewport coordinates to map coordinates
-		// Calculation is scaled by 4 to avoid rounding errors
+		/* Convert viewport coordinates to map coordinates
+		 * Calculation is scaled by 4 to avoid rounding errors */
 		vx = -x + y * 2;
 		vy =  x + y * 2;
-		// clamp to size of map
+		/* clamp to size of map */
 		vx = clamp(vx, 0 * 4, MapMaxX() * TILE_SIZE * 4);
 		vy = clamp(vy, 0 * 4, MapMaxY() * TILE_SIZE * 4);
-		// Convert map coordinates to viewport coordinates
+		/* Convert map coordinates to viewport coordinates */
 		x = (-vx + vy) / 2;
 		y = ( vx + vy) / 4;
-		// Set position
+		/* Set position */
 		WP(w, vp_d).scrollpos_x = x - vp->virtual_width / 2;
 		WP(w, vp_d).scrollpos_y = y - vp->virtual_height / 2;
 
@@ -1859,13 +1859,13 @@ void SetTileSelectBigSize(int ox, int oy, int sx, int sy)
 	_thd.new_outersize.y = sy * TILE_SIZE;
 }
 
-/* returns the best autorail highlight type from map coordinates */
+/** returns the best autorail highlight type from map coordinates */
 static byte GetAutorailHT(int x, int y)
 {
 	return HT_RAIL | _AutorailPiece[x & 0xF][y & 0xF];
 }
 
-// called regular to update tile highlighting in all cases
+/** called regular to update tile highlighting in all cases */
 void UpdateTileSelection()
 {
 	int x1;
@@ -1912,13 +1912,13 @@ void UpdateTileSelection()
 		}
 	}
 
-	// redraw selection
+	/* redraw selection */
 	if (_thd.drawstyle != _thd.new_drawstyle ||
 			_thd.pos.x != _thd.new_pos.x || _thd.pos.y != _thd.new_pos.y ||
 			_thd.size.x != _thd.new_size.x || _thd.size.y != _thd.new_size.y ||
 	    _thd.outersize.x != _thd.new_outersize.x ||
 	    _thd.outersize.y != _thd.new_outersize.y) {
-		// clear the old selection?
+		/* clear the old selection? */
 		if (_thd.drawstyle) SetSelectionTilesDirty();
 
 		_thd.drawstyle = _thd.new_drawstyle;
@@ -1927,12 +1927,12 @@ void UpdateTileSelection()
 		_thd.outersize = _thd.new_outersize;
 		_thd.dirty = 0xff;
 
-		// draw the new selection?
+		/* draw the new selection? */
 		if (_thd.new_drawstyle) SetSelectionTilesDirty();
 	}
 }
 
-// highlighting tiles while only going over them with the mouse
+/** highlighting tiles while only going over them with the mouse */
 void VpStartPlaceSizing(TileIndex tile, int user)
 {
 	_thd.userdata = user;
@@ -1982,7 +1982,7 @@ static void VpStartPreSizing()
 	_special_mouse_mode = WSM_PRESIZE;
 }
 
-/* returns information about the 2x1 piece to be build.
+/** returns information about the 2x1 piece to be build.
  * The lower bits (0-3) are the track type. */
 static byte Check2x1AutoRail(int mode)
 {
@@ -2133,7 +2133,7 @@ static int CalcHeightdiff(HighLightStyle style, uint distance, TileIndex start_t
 
 static const StringID measure_strings_length[] = {STR_NULL, STR_MEASURE_LENGTH, STR_MEASURE_LENGTH_HEIGHTDIFF};
 
-// while dragging
+/** while dragging */
 static void CalcRaildirsDrawstyle(TileHighlightData *thd, int x, int y, int method)
 {
 	HighLightStyle b;
@@ -2384,7 +2384,7 @@ calc_heightdiff_single_direction:;
 	_thd.selend.y = y;
 }
 
-// while dragging
+/** while dragging */
 bool VpHandlePlaceSizingDrag()
 {
 	Window *w;
@@ -2394,14 +2394,14 @@ bool VpHandlePlaceSizingDrag()
 
 	e.we.place.userdata = _thd.userdata;
 
-	// stop drag mode if the window has been closed
+	/* stop drag mode if the window has been closed */
 	w = FindWindowById(_thd.window_class,_thd.window_number);
 	if (w == NULL) {
 		ResetObjectToPlace();
 		return false;
 	}
 
-	// while dragging execute the drag procedure of the corresponding window (mostly VpSelectTilesWithMethod() )
+	/* while dragging execute the drag procedure of the corresponding window (mostly VpSelectTilesWithMethod() ) */
 	if (_left_button_down) {
 		e.event = WE_PLACE_DRAG;
 		e.we.place.pt = GetTileBelowCursor();
@@ -2409,8 +2409,8 @@ bool VpHandlePlaceSizingDrag()
 		return false;
 	}
 
-	// mouse button released..
-	// keep the selected tool, but reset it to the original mode.
+	/* mouse button released..
+	 * keep the selected tool, but reset it to the original mode. */
 	_special_mouse_mode = WSM_NONE;
 	if (_thd.next_drawstyle == HT_RECT) {
 		_thd.place_mode = VHM_RECT;
@@ -2425,7 +2425,7 @@ bool VpHandlePlaceSizingDrag()
 	}
 	SetTileSelectSize(1, 1);
 
-	// and call the mouseup event.
+	/* and call the mouseup event. */
 	e.event = WE_PLACE_MOUSEUP;
 	e.we.place.pt = _thd.selend;
 	e.we.place.tile = TileVirtXY(e.we.place.pt.x, e.we.place.pt.y);
@@ -2446,7 +2446,7 @@ void SetObjectToPlace(CursorID icon, SpriteID pal, byte mode, WindowClass window
 {
 	Window *w;
 
-	// undo clicking on button
+	/* undo clicking on button */
 	if (_thd.place_mode != 0) {
 		_thd.place_mode = 0;
 		w = FindWindowById(_thd.window_class, _thd.window_number);
diff --git a/src/viewport.h b/src/viewport.h
index 4d19ab6c4..f40a671ee 100644
--- a/src/viewport.h
+++ b/src/viewport.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file viewport.h */
+
 #ifndef VIEWPORT_H
 #define VIEWPORT_H
 
@@ -15,7 +17,7 @@ struct ViewPort {
 
 void SetSelectionRed(bool);
 
-/* viewport.c */
+/* viewport.cpp */
 void InitViewports();
 void DeleteWindowViewport(Window *w);
 void AssignWindowViewport(Window *w, int x, int y,
@@ -74,28 +76,28 @@ enum {
 	VPM_SIGNALDIRS      = 6
 };
 
-// viewport highlight mode (for highlighting tiles below cursor)
+/* viewport highlight mode (for highlighting tiles below cursor) */
 enum {
-	VHM_NONE    = 0, // default
-	VHM_RECT    = 1, // rectangle (stations, depots, ...)
-	VHM_POINT   = 2, // point (lower land, raise land, level land, ...)
-	VHM_SPECIAL = 3, // special mode used for highlighting while dragging (and for tunnels/docks)
-	VHM_DRAG    = 4, // dragging items in the depot windows
-	VHM_RAIL    = 5, // rail pieces
+	VHM_NONE    = 0, ///< default
+	VHM_RECT    = 1, ///< rectangle (stations, depots, ...)
+	VHM_POINT   = 2, ///< point (lower land, raise land, level land, ...)
+	VHM_SPECIAL = 3, ///< special mode used for highlighting while dragging (and for tunnels/docks)
+	VHM_DRAG    = 4, ///< dragging items in the depot windows
+	VHM_RAIL    = 5, ///< rail pieces
 };
 
 void VpSelectTilesWithMethod(int x, int y, int method);
 
-// highlighting draw styles
+/* highlighting draw styles */
 typedef byte HighLightStyle;
 enum HighLightStyles {
 	HT_NONE   = 0x00,
 	HT_RECT   = 0x80,
 	HT_POINT  = 0x40,
-	HT_LINE   = 0x20, /* used for autorail highlighting (longer streches)
-	                   * (uses lower bits to indicate direction) */
-	HT_RAIL   = 0x10, /* autorail (one piece)
-	                  * (uses lower bits to indicate direction) */
+	HT_LINE   = 0x20,    ///< used for autorail highlighting (longer streches)
+	                     ///< (uses lower bits to indicate direction)
+	HT_RAIL   = 0x10,    ///< autorail (one piece)
+	                     ///< (uses lower bits to indicate direction)
 	HT_DRAG_MASK = 0xF0, ///< masks the drag-type
 
 	/* lower bits (used with HT_LINE and HT_RAIL):
@@ -138,7 +140,7 @@ struct TileHighlightData {
 };
 
 
-// common button handler
+/* common button handler */
 bool HandlePlacePushButton(Window *w, int widget, CursorID cursor, int mode, PlaceProc *placeproc);
 
 VARDEF Point _tile_fract_coords;
diff --git a/src/void_map.h b/src/void_map.h
index 06c2570f9..a5a14684b 100644
--- a/src/void_map.h
+++ b/src/void_map.h
@@ -1,5 +1,7 @@
 /* $Id$ */
 
+/** @file void_map.h */
+
 #ifndef VOID_MAP_H
 #define VOID_MAP_H