(svn r21088) -Doc: Additions/corrections of doxygen comments.

13 files changed, 258 insertions, 121 deletions

diff --git a/src/aircraft.h b/src/aircraft.h
index a0ff21833..ec55b53ab 100644
--- a/src/aircraft.h
+++ b/src/aircraft.h
@@ -17,7 +17,7 @@
 
 struct Aircraft;
 
-/** An aircraft can be one ot those types */
+/** An aircraft can be one of those types. */
 enum AircraftSubType {
 	AIR_HELICOPTER = 0, ///< an helicopter
 	AIR_AIRCRAFT   = 2, ///< an airplane
@@ -27,7 +27,7 @@ enum AircraftSubType {
 
 
 /**
- * Handle Aircraft specific tasks when a an Aircraft enters a hangar
+ * Handle Aircraft specific tasks when an Aircraft enters a hangar
  * @param *v Vehicle that enters the hangar
  */
 void HandleAircraftEnterHangar(Aircraft *v);
@@ -67,18 +67,16 @@ struct AircraftCache {
  * Aircraft, helicopters, rotors and their shadows belong to this class.
  */
 struct Aircraft : public SpecializedVehicle<Aircraft, VEH_AIRCRAFT> {
-	AircraftCache acache; ///< Cache of often used calculated values
+	AircraftCache acache;          ///< Cache of often used calculated values
 
-	uint16 crashed_counter;
-	byte pos;
-	byte previous_pos;
-	StationID targetairport;
-	byte state;
+	uint16 crashed_counter;        ///< Timer for handling crash animations.
+	byte pos;                      ///< Next desired position of the aircraft.
+	byte previous_pos;             ///< Previous desired position of the aircraft.
+	StationID targetairport;       ///< Airport to go to next.
+	byte state;                    ///< State of the airport. @see AirportMovementStates
 	DirectionByte last_direction;
-	byte number_consecutive_turns;
-
-	/** Ticks between each turn to prevent > 45 degree turns. */
-	byte turn_counter;
+	byte number_consecutive_turns; ///< Protection to prevent the aircraft of making a lot of turns in order to reach a specific point.
+	byte turn_counter;             ///< Ticks between each turn to prevent > 45 degree turns.
 
 	/** We don't want GCC to zero our struct! It already is zeroed and has an index! */
 	Aircraft() : SpecializedVehicle<Aircraft, VEH_AIRCRAFT>() {}
@@ -116,6 +114,9 @@ struct Aircraft : public SpecializedVehicle<Aircraft, VEH_AIRCRAFT> {
 	}
 };
 
+/**
+ * Macro for iterating over all aircrafts.
+ */
 #define FOR_ALL_AIRCRAFT(var) FOR_ALL_VEHICLES_OF_TYPE(Aircraft, var)
 
 SpriteID GetRotorImage(const Aircraft *v);
diff --git a/src/aircraft_cmd.cpp b/src/aircraft_cmd.cpp
index 907fedb58..217d297ee 100644
--- a/src/aircraft_cmd.cpp
+++ b/src/aircraft_cmd.cpp
@@ -461,6 +461,13 @@ static void HelicopterTickHandler(Aircraft *v)
 	VehicleMove(u, true);
 }
 
+/**
+ * Set aircraft position.
+ * @param v Aircraft to position.
+ * @param x New X position.
+ * @param y New y position.
+ * @param z New z position.
+ */
 void SetAircraftPosition(Aircraft *v, int x, int y, int z)
 {
 	v->x_pos = x;
@@ -494,7 +501,7 @@ void SetAircraftPosition(Aircraft *v, int x, int y, int z)
 }
 
 /**
- * Handle Aircraft specific tasks when a an Aircraft enters a hangar
+ * Handle Aircraft specific tasks when an Aircraft enters a hangar
  * @param *v Vehicle that enters the hangar
  */
 void HandleAircraftEnterHangar(Aircraft *v)
@@ -959,7 +966,10 @@ static bool AircraftController(Aircraft *v)
 	return false;
 }
 
-
+/**
+ * Handle crashed aircraft \a v.
+ * @param v Crashed aircraft.
+ */
 static bool HandleCrashedAircraft(Aircraft *v)
 {
 	v->crashed_counter += 3;
@@ -1103,6 +1113,10 @@ uint Aircraft::Crash(bool flooded)
 	return pass;
 }
 
+/**
+ * Bring the aircraft in a crashed state, create the explosion animation, and create a news item about the crash.
+ * @param v Aircraft that crashed.
+ */
 static void CrashAirplane(Aircraft *v)
 {
 	CreateEffectVehicleRel(v, 4, 4, 8, EV_EXPLOSION_LARGE);
@@ -1131,6 +1145,10 @@ static void CrashAirplane(Aircraft *v)
 	SndPlayVehicleFx(SND_12_EXPLOSION, v);
 }
 
+/**
+ * Decide whether aircraft \a v should crash.
+ * @param v Aircraft to test.
+ */
 static void MaybeCrashAirplane(Aircraft *v)
 {
 	if (_settings_game.vehicle.plane_crashes == 0) return;
@@ -1158,7 +1176,11 @@ static void MaybeCrashAirplane(Aircraft *v)
 	CrashAirplane(v);
 }
 
-/** we've landed and just arrived at a terminal */
+/**
+ * Aircraft arrives at a terminal. If it is the first aircraft, throw a party.
+ * Start loading cargo.
+ * @param v Aircraft that arrived.
+ */
 static void AircraftEntersTerminal(Aircraft *v)
 {
 	if (v->current_order.IsType(OT_GOTO_DEPOT)) return;
@@ -1183,6 +1205,10 @@ static void AircraftEntersTerminal(Aircraft *v)
 	v->BeginLoading();
 }
 
+/**
+ * Aircraft touched down at the landing strip.
+ * @param v Aircraft that landed.
+ */
 static void AircraftLandAirplane(Aircraft *v)
 {
 	v->UpdateDeltaXY(INVALID_DIR);
@@ -1240,13 +1266,22 @@ static void AircraftEventHandler_EnterTerminal(Aircraft *v, const AirportFTAClas
 	v->state = apc->layout[v->pos].heading;
 }
 
+/**
+ * Aircraft arrived in an airport hangar.
+ * @param v Aircraft in the hangar.
+ * @param apc Airport description containing the hangar.
+ */
 static void AircraftEventHandler_EnterHangar(Aircraft *v, const AirportFTAClass *apc)
 {
 	VehicleEnterDepot(v);
 	v->state = apc->layout[v->pos].heading;
 }
 
-/** In an Airport Hangar */
+/**
+ * Handle aircraft movement/decision making in an airport hangar.
+ * @param v Aircraft in the hangar.
+ * @param apc Airport description containing the hangar.
+ */
 static void AircraftEventHandler_InHangar(Aircraft *v, const AirportFTAClass *apc)
 {
 	/* if we just arrived, execute EnterHangar first */
@@ -1469,7 +1504,13 @@ static void AircraftEventHandler_HeliEndLanding(Aircraft *v, const AirportFTACla
 	v->state = Station::Get(v->targetairport)->airport.HasHangar() ? HANGAR : HELITAKEOFF;
 }
 
+/**
+ * Signature of the aircraft handler function.
+ * @param v Aircraft to handle.
+ * @param apc Airport state machine.
+ */
 typedef void AircraftStateHandler(Aircraft *v, const AirportFTAClass *apc);
+/** Array of handler functions for each target of the aircraft. */
 static AircraftStateHandler * const _aircraft_state_handlers[] = {
 	AircraftEventHandler_General,        // TO_ALL         =  0
 	AircraftEventHandler_InHangar,       // HANGAR         =  1
@@ -1564,7 +1605,7 @@ static bool AirportMove(Aircraft *v, const AirportFTAClass *apc)
 	NOT_REACHED();
 }
 
-/*  returns true if the road ahead is busy, eg. you must wait before proceeding */
+/** returns true if the road ahead is busy, eg. you must wait before proceeding. */
 static bool AirportHasBlock(Aircraft *v, const AirportFTA *current_pos, const AirportFTAClass *apc)
 {
 	const AirportFTA *reference = &apc->layout[v->pos];
@@ -1658,6 +1699,13 @@ static const MovementTerminalMapping _airport_terminal_mapping[] = {
 	{HELIPAD3, HELIPAD3_block},
 };
 
+/**
+ * Find a free terminal or helipad, and if available, assign it.
+ * @param v Aircraft looking for a free terminal or helipad.
+ * @param i First terminal to examine.
+ * @param last_terminal Terminal number to stop examining.
+ * @return A terminal or helipad has been found, and has been assigned to the aircraft.
+ */
 static bool FreeTerminal(Aircraft *v, byte i, byte last_terminal)
 {
 	assert(last_terminal <= lengthof(_airport_terminal_mapping));
@@ -1673,6 +1721,11 @@ static bool FreeTerminal(Aircraft *v, byte i, byte last_terminal)
 	return false;
 }
 
+/**
+ * Get the number of terminals at the airport.
+ * @param afc Airport description.
+ * @return Number of terminals.
+ */
 static uint GetNumTerminals(const AirportFTAClass *apc)
 {
 	uint num = 0;
@@ -1682,6 +1735,12 @@ static uint GetNumTerminals(const AirportFTAClass *apc)
 	return num;
 }
 
+/**
+ * Find a free terminal, and assign it if available.
+ * @param v Aircraft to handle.
+ * @param apc Airport state machine.
+ * @return Found a free terminal and assigned it.
+ */
 static bool AirportFindFreeTerminal(Aircraft *v, const AirportFTAClass *apc)
 {
 	/* example of more terminalgroups
@@ -1729,6 +1788,12 @@ static bool AirportFindFreeTerminal(Aircraft *v, const AirportFTAClass *apc)
 	return FreeTerminal(v, 0, GetNumTerminals(apc));
 }
 
+/**
+ * Find a free helipad, and assign it if available.
+ * @param v Aircraft to handle.
+ * @param apc Airport state machine.
+ * @return Found a free helipad and assigned it.
+ */
 static bool AirportFindFreeHelipad(Aircraft *v, const AirportFTAClass *apc)
 {
 	/* if an airport doesn't have helipads, use terminals */
diff --git a/src/airport.cpp b/src/airport.cpp
index 165a33017..1141d78c1 100644
--- a/src/airport.cpp
+++ b/src/airport.cpp
@@ -20,9 +20,21 @@
 	static AirportFTAClass _airportfta_ ## name(_airport_moving_data_ ## name, terminals, \
 			num_helipads, _airport_entries_ ## name, flags, _airport_fta_ ## name, delta_z);
 
+/**
+ * Define an airport.
+ * @param name Suffix of the names of the airport data.
+ * @param num_helipads Number of heli pads.
+ * @param short_strip Airport has a short land/take-off strip.
+ */
 #define AIRPORT(name, num_helipads, short_strip) \
 	AIRPORT_GENERIC(name, _airport_terminal_ ## name, num_helipads, AirportFTAClass::ALL | (short_strip ? AirportFTAClass::SHORT_STRIP : (AirportFTAClass::Flags)0), 0)
 
+/**
+ * Define a heliport.
+ * @param name Suffix of the names of the helipad data.
+ * @param num_helipads Number of heli pads.
+ * @param delta_z Height of the arport above the land.
+ */
 #define HELIPORT(name, num_helipads, delta_z) \
 	AIRPORT_GENERIC(name, NULL, num_helipads, AirportFTAClass::HELICOPTERS, delta_z)
 
@@ -53,6 +65,8 @@ static AirportFTA *AirportBuildAutomata(uint nofelements, const AirportFTAbuildu
  * Rotate the airport moving data to another rotation.
  * @param orig Pointer to the moving data to rotate.
  * @param rotation How to rotate the moving data.
+ * @param num_tiles_x Number of tiles in x direction.
+ * @param num_tiles_y Number of tiles in y direction.
  * @return The rotated moving data.
  */
 AirportMovingData RotateAirportMovingData(const AirportMovingData *orig, Direction rotation, uint num_tiles_x, uint num_tiles_y)
@@ -172,6 +186,11 @@ static AirportFTA *AirportBuildAutomata(uint nofelements, const AirportFTAbuildu
 	return FAutomata;
 }
 
+/**
+ * Get the finite state machine of an airport type.
+ * @param airport_type Airport type to query FTA from. @see AirportTypes
+ * @return Finite state machine of the airport.
+ */
 const AirportFTAClass *GetAirport(const byte airport_type)
 {
 	if (airport_type == AT_DUMMY) return &_airportfta_dummy;
diff --git a/src/airport.h b/src/airport.h
index 5bea9b50d..d9fe35e3a 100644
--- a/src/airport.h
+++ b/src/airport.h
@@ -26,72 +26,72 @@ static const uint INVALID_AIRPORTTILE    = NUM_AIRPORTTILES; ///< id for an inva
 
 /** Airport types */
 enum AirportTypes {
-	AT_SMALL         =   0,
-	AT_LARGE         =   1,
-	AT_HELIPORT      =   2,
-	AT_METROPOLITAN  =   3,
-	AT_INTERNATIONAL =   4,
-	AT_COMMUTER      =   5,
-	AT_HELIDEPOT     =   6,
-	AT_INTERCON      =   7,
-	AT_HELISTATION   =   8,
-	AT_OILRIG        =   9,
-	NEW_AIRPORT_OFFSET = 10,
-	NUM_AIRPORTS     =  128,
-	AT_INVALID       = 254,
-	AT_DUMMY         = 255
+	AT_SMALL           =   0, ///< Small airport.
+	AT_LARGE           =   1, ///< Large airport.
+	AT_HELIPORT        =   2, ///< Heli port.
+	AT_METROPOLITAN    =   3, ///< Metropolitan airport.
+	AT_INTERNATIONAL   =   4, ///< International airport.
+	AT_COMMUTER        =   5, ///< Commuter airport.
+	AT_HELIDEPOT       =   6, ///< Heli depot.
+	AT_INTERCON        =   7, ///< Intercontinental airport.
+	AT_HELISTATION     =   8, ///< Heli station airport.
+	AT_OILRIG          =   9, ///< Oilrig airport.
+	NEW_AIRPORT_OFFSET =  10, ///< Number of the first newgrf airport.
+	NUM_AIRPORTS       = 128, ///< Maximal number of airports.
+	AT_INVALID         = 254, ///< Invalid airport.
+	AT_DUMMY           = 255, ///< Dummy airport.
 };
 
+/** Flags for airport movement data. */
 enum AirportMovingDataFlags {
-	AMED_NOSPDCLAMP = 1 << 0,
-	AMED_TAKEOFF    = 1 << 1,
-	AMED_SLOWTURN   = 1 << 2,
-	AMED_LAND       = 1 << 3,
-	AMED_EXACTPOS   = 1 << 4,
-	AMED_BRAKE      = 1 << 5,
-	AMED_HELI_RAISE = 1 << 6,
-	AMED_HELI_LOWER = 1 << 7,
-	AMED_HOLD       = 1 << 8
+	AMED_NOSPDCLAMP = 1 << 0, ///< No speed restrictions.
+	AMED_TAKEOFF    = 1 << 1, ///< Takeoff movement.
+	AMED_SLOWTURN   = 1 << 2, ///< Turn slowly (mostly used in the air).
+	AMED_LAND       = 1 << 3, ///< Landing onto landing strip.
+	AMED_EXACTPOS   = 1 << 4, ///< Go exactly to the destination coordinates.
+	AMED_BRAKE      = 1 << 5, ///< Taxiing at the airport.
+	AMED_HELI_RAISE = 1 << 6, ///< Helicopter take-off.
+	AMED_HELI_LOWER = 1 << 7, ///< Helicopter landing.
+	AMED_HOLD       = 1 << 8  ///< Holding pattern movement (above the airport).
 };
 
-/* Movement States on Airports (headings target) */
+/** Movement States on Airports (headings target) */
 enum AirportMovementStates {
-	TO_ALL         =  0,
-	HANGAR         =  1,
-	TERM1          =  2,
-	TERM2          =  3,
-	TERM3          =  4,
-	TERM4          =  5,
-	TERM5          =  6,
-	TERM6          =  7,
-	HELIPAD1       =  8,
-	HELIPAD2       =  9,
-	TAKEOFF        = 10,
-	STARTTAKEOFF   = 11,
-	ENDTAKEOFF     = 12,
-	HELITAKEOFF    = 13,
-	FLYING         = 14,
-	LANDING        = 15,
-	ENDLANDING     = 16,
-	HELILANDING    = 17,
-	HELIENDLANDING = 18,
-	TERM7          = 19,
-	TERM8          = 20,
-	HELIPAD3       = 21,
-	MAX_HEADINGS   = 21,
+	TO_ALL         =  0, ///< Go in this direction for every target.
+	HANGAR         =  1, ///< Heading for hangar.
+	TERM1          =  2, ///< Heading for terminal 1.
+	TERM2          =  3, ///< Heading for terminal 2.
+	TERM3          =  4, ///< Heading for terminal 3.
+	TERM4          =  5, ///< Heading for terminal 4.
+	TERM5          =  6, ///< Heading for terminal 5.
+	TERM6          =  7, ///< Heading for terminal 6.
+	HELIPAD1       =  8, ///< Heading for helipad 1.
+	HELIPAD2       =  9, ///< Heading for helipad 2.
+	TAKEOFF        = 10, ///< Airplane wants to leave the airport.
+	STARTTAKEOFF   = 11, ///< Airplane has arrived at a runway for take-off.
+	ENDTAKEOFF     = 12, ///< Airplane has reached end-point of the take-off runway.
+	HELITAKEOFF    = 13, ///< Helicopter wants to leave the airport.
+	FLYING         = 14, ///< Vehicle is flying in the air.
+	LANDING        = 15, ///< Airplane wants to land.
+	ENDLANDING     = 16, ///< Airplane wants to finish landing.
+	HELILANDING    = 17, ///< Helicopter wants to land.
+	HELIENDLANDING = 18, ///< Helicopter wants to finish landing.
+	TERM7          = 19, ///< Heading for terminal 7.
+	TERM8          = 20, ///< Heading for terminal 8.
+	HELIPAD3       = 21, ///< Heading for helipad 3.
+	MAX_HEADINGS   = 21, ///< Last valid target to head for.
 };
 
-/* Movement Blocks on Airports
- * blocks (eg_airport_flags) */
+/** Movement Blocks on Airports blocks (eg_airport_flags). */
 static const uint64
-	TERM1_block              = 1ULL <<  0,
-	TERM2_block              = 1ULL <<  1,
-	TERM3_block              = 1ULL <<  2,
-	TERM4_block              = 1ULL <<  3,
-	TERM5_block              = 1ULL <<  4,
-	TERM6_block              = 1ULL <<  5,
-	HELIPAD1_block           = 1ULL <<  6,
-	HELIPAD2_block           = 1ULL <<  7,
+	TERM1_block              = 1ULL <<  0, ///< Block belonging to terminal 1.
+	TERM2_block              = 1ULL <<  1, ///< Block belonging to terminal 2.
+	TERM3_block              = 1ULL <<  2, ///< Block belonging to terminal 3.
+	TERM4_block              = 1ULL <<  3, ///< Block belonging to terminal 4.
+	TERM5_block              = 1ULL <<  4, ///< Block belonging to terminal 5.
+	TERM6_block              = 1ULL <<  5, ///< Block belonging to terminal 6.
+	HELIPAD1_block           = 1ULL <<  6, ///< Block belonging to helipad 1.
+	HELIPAD2_block           = 1ULL <<  7, ///< Block belonging to helipad 2.
 	RUNWAY_IN_OUT_block      = 1ULL <<  8,
 	RUNWAY_IN_block          = 1ULL <<  8,
 	AIRPORT_BUSY_block       = 1ULL <<  8,
@@ -110,15 +110,15 @@ static const uint64
 	PRE_HELIPAD_block        = 1ULL << 21,
 
 	/* blocks for new airports */
-	TERM7_block              = 1ULL << 22,
-	TERM8_block              = 1ULL << 23,
-	HELIPAD3_block           = 1ULL << 24,
+	TERM7_block              = 1ULL << 22, ///< Block belonging to terminal 7.
+	TERM8_block              = 1ULL << 23, ///< Block belonging to terminal 8.
+	HELIPAD3_block           = 1ULL << 24, ///< Block belonging to helipad 3.
 	HANGAR1_AREA_block       = 1ULL << 26,
 	OUT_WAY2_block           = 1ULL << 27,
 	IN_WAY2_block            = 1ULL << 28,
 	RUNWAY_IN2_block         = 1ULL << 29,
-	RUNWAY_OUT2_block        = 1ULL << 10,   ///< note re-uses TAXIWAY_BUSY
-	HELIPAD_GROUP_block      = 1ULL << 13,   ///< note re-uses AIRPORT_ENTRANCE
+	RUNWAY_OUT2_block        = 1ULL << 10, ///< @note re-uses #TAXIWAY_BUSY_block
+	HELIPAD_GROUP_block      = 1ULL << 13, ///< @note re-uses #AIRPORT_ENTRANCE_block
 	OUT_WAY_block2           = 1ULL << 31,
 	/* end of new blocks */
 
@@ -126,17 +126,17 @@ static const uint64
 
 /** A single location on an airport where aircraft can move to. */
 struct AirportMovingData {
-	int16 x;                 ///< x-coordinate of this position
-	int16 y;                 ///< y-coordinate of this position
-	uint16 flag;             ///< special flags when moving towards this position
-	DirectionByte direction; ///< Direction to turn the aircraft after reaching this position.
+	int16 x;                 ///< x-coordinate of the destination.
+	int16 y;                 ///< y-coordinate of the destination.
+	uint16 flag;             ///< special flags when moving towards the destination.
+	DirectionByte direction; ///< Direction to turn the aircraft after reaching the destination.
 };
 
 AirportMovingData RotateAirportMovingData(const AirportMovingData *orig, Direction rotation, uint num_tiles_x, uint num_tiles_y);
 
 struct AirportFTAbuildup;
 
-/** Finite sTate mAchine --> FTA */
+/** Finite sTate mAchine (FTA) of an airport. */
 struct AirportFTAClass {
 public:
 	/** Bitmask of airport flags. */
@@ -159,17 +159,22 @@ public:
 
 	~AirportFTAClass();
 
+	/**
+	 * Get movement data at a position.
+	 * @param position Element number to get movement data about.
+	 * @return Pointer to the movement data.
+	 */
 	const AirportMovingData *MovingData(byte position) const
 	{
 		assert(position < nofelements);
 		return &moving_data[position];
 	}
 
-	const AirportMovingData *moving_data;
+	const AirportMovingData *moving_data; ///< Movement data.
 	struct AirportFTA *layout;            ///< state machine for airport
-	const byte *terminals;
+	const byte *terminals;                ///< Array with the number of terminal groups, followed by the number of terminals in each group.
 	const byte num_helipads;              ///< Number of helipads on this airport. When 0 helicopters will go to normal terminals.
-	Flags flags;
+	Flags flags;                          ///< Flags for this airport type.
 	byte nofelements;                     ///< number of positions the airport consists of
 	const byte *entry_points;             ///< when an airplane arrives at this airport, enter it at position entry_point, index depends on direction
 	byte delta_z;                         ///< Z adjustment for helicopter pads
diff --git a/src/newgrf_airport.cpp b/src/newgrf_airport.cpp
index d808936a2..ad02efd8d 100644
--- a/src/newgrf_airport.cpp
+++ b/src/newgrf_airport.cpp
@@ -37,7 +37,7 @@ INSTANTIATE_NEWGRF_CLASS_METHODS(AirportClass, AirportSpec, AirportClassID, APC_
 
 AirportOverrideManager _airport_mngr(NEW_AIRPORT_OFFSET, NUM_AIRPORTS, AT_INVALID);
 
-AirportSpec AirportSpec::specs[NUM_AIRPORTS];
+AirportSpec AirportSpec::specs[NUM_AIRPORTS]; ///< Airport specifications.
 
 /**
  * Retrieve airport spec for the given airport. If an override is available
@@ -70,7 +70,7 @@ AirportSpec AirportSpec::specs[NUM_AIRPORTS];
 	return &AirportSpec::specs[type];
 }
 
-/** Check if this airport is available to build. */
+/** Check whether this airport is available to build. */
 bool AirportSpec::IsAvailable() const
 {
 	if (!this->enabled) return false;
diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp
index 2689af8a5..1254dc269 100644
--- a/src/roadveh_cmd.cpp
+++ b/src/roadveh_cmd.cpp
@@ -604,6 +604,11 @@ static RoadVehicle *RoadVehFindCloseTo(RoadVehicle *v, int x, int y, Direction d
 	return RoadVehicle::From(rvf.best);
 }
 
+/**
+ * A road vehicle arrives at a station. If it is the first time, create a news item.
+ * @param v  Road vehicle that arrived.
+ * @param st Station where the road vehicle arrived.
+ */
 static void RoadVehArrivesAt(const RoadVehicle *v, Station *st)
 {
 	if (v->IsBus()) {
diff --git a/src/ship_cmd.cpp b/src/ship_cmd.cpp
index 019693547..24e9eb654 100644
--- a/src/ship_cmd.cpp
+++ b/src/ship_cmd.cpp
@@ -317,6 +317,11 @@ static bool ShipAccelerate(Vehicle *v)
 	return (t < v->progress);
 }
 
+/**
+ * Ship arrives at a dock. If it is the first time, send out a news item.
+ * @param v  Ship that arrived.
+ * @param st Station being visited.
+ */
 static void ShipArrivesAt(const Vehicle *v, Station *st)
 {
 	/* Check if station was ever visited before */
diff --git a/src/table/airport_movement.h b/src/table/airport_movement.h
index 523d17693..e18c639a2 100644
--- a/src/table/airport_movement.h
+++ b/src/table/airport_movement.h
@@ -13,20 +13,30 @@
 #define AIRPORT_MOVEMENT_H
 
 
-/* state machine input struct (from external file, etc.)
- * Finite sTate mAchine --> FTA */
+/**
+ * State machine input struct (from external file, etc.)
+ * Finite sTate mAchine --> FTA
+ */
 struct AirportFTAbuildup {
-	byte position; // the position that an airplane is at
-	byte heading;  // the current orders (eg. TAKEOFF, HANGAR, ENDLANDING, etc.)
-	uint64 block;  // the block this position is on on the airport (st->airport.flags)
-	byte next;     // next position from this position
+	byte position; ///< The position that an airplane is at.
+	byte heading;  ///< The current orders (eg. TAKEOFF, HANGAR, ENDLANDING, etc.).
+	uint64 block;  ///< The block this position is on on the airport (st->airport.flags).
+	byte next;     ///< Next position from this position.
 };
 
 ///////////////////////////////////////////////////////////////////////
 /////*********Movement Positions on Airports********************///////
 
+/**
+ * Airport movement data creation macro.
+ * @param x     X position.
+ * @param y     Y position.
+ * @param flags Movement flags.
+ * @param dir   Direction.
+ */
 #define AMD(x, y, flags, dir) { x, y, flags, {dir} }
 
+/** Dummy airport. */
 static const AirportMovingData _airport_moving_data_dummy[] = {
 	AMD(    0,    0, AMED_NOSPDCLAMP | AMED_SLOWTURN,     DIR_N ),
 	AMD(    0,   96, AMED_NOSPDCLAMP | AMED_SLOWTURN,     DIR_N ),
@@ -34,7 +44,7 @@ static const AirportMovingData _airport_moving_data_dummy[] = {
 	AMD(   96,    0, AMED_NOSPDCLAMP | AMED_SLOWTURN,     DIR_N ),
 };
 
-/* Country Airfield (small) 4x3 */
+/** Country Airfield (small) 4x3. */
 static const AirportMovingData _airport_moving_data_country[22] = {
 	AMD(   53,    3, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar
 	AMD(   53,   27, 0,                               DIR_N ), // 01 Taxi to right outside depot
@@ -60,7 +70,7 @@ static const AirportMovingData _airport_moving_data_country[22] = {
 	AMD(   44,   40, AMED_HELI_LOWER,                 DIR_N ), // 21 Helicopter landing
 };
 
-/* Commuter Airfield (small) 5x4 */
+/** Commuter Airfield (small) 5x4. */
 static const AirportMovingData _airport_moving_data_commuter[37] = {
 	AMD(   69,    3, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar
 	AMD(   72,   22, 0,                               DIR_N ), // 01 Taxi to right outside depot
@@ -102,7 +112,7 @@ static const AirportMovingData _airport_moving_data_commuter[37] = {
 	AMD(   56,    8, AMED_EXACTPOS,                   DIR_N ), // pre-helitakeoff helipad 2
 };
 
-/* City Airport (large) 6x6 */
+/** City Airport (large) 6x6. */
 static const AirportMovingData _airport_moving_data_city[] = {
 	AMD(   85,    3, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar
 	AMD(   85,   22, 0,                               DIR_N ), // 01 Taxi to right outside depot
@@ -132,11 +142,11 @@ static const AirportMovingData _airport_moving_data_city[] = {
 	AMD(  145,    1, AMED_HOLD       | AMED_SLOWTURN, DIR_N ), // 25 Fly around waiting for a landing spot (north-west)
 	AMD(  -32,    1, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 26 Initial approach fix (north)
 	AMD(  300,  -48, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 27 Initial approach fix (south)
-	AMD(  140,  -48, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 28 Intermediadate Approach fix (south), IAF (west)
+	AMD(  140,  -48, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 28 Intermediate Approach fix (south), IAF (west)
 	AMD(  -32,  120, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 29 Initial approach fix (east)
 };
 
-/* Metropolitan Airport (metropolitan) - 2 runways */
+/** Metropolitan Airport (metropolitan) - 2 runways. */
 static const AirportMovingData _airport_moving_data_metropolitan[28] = {
 	AMD(   85,    3, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar
 	AMD(   85,   22, 0,                               DIR_N ), // 01 Taxi to right outside depot
@@ -168,7 +178,7 @@ static const AirportMovingData _airport_moving_data_metropolitan[28] = {
 	AMD(   21,   58, AMED_EXACTPOS,                   DIR_SW), // 27 Transitions after landing to on-ground movement
 };
 
-/* International Airport (international) - 2 runways, 6 terminals, dedicated helipod */
+/** International Airport (international) - 2 runways, 6 terminals, dedicated helipad. */
 static const AirportMovingData _airport_moving_data_international[51] = {
 	AMD(    7,   55, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar 1
 	AMD(  100,   21, AMED_EXACTPOS,                   DIR_SE), // 01 In Hangar 2
@@ -224,7 +234,7 @@ static const AirportMovingData _airport_moving_data_international[51] = {
 	AMD(  104,   32, AMED_HELI_LOWER,                 DIR_N ), // 50 Land in HANGAR2_AREA to go to hangar
 };
 
-/* Intercontinental Airport - 4 runways, 8 terminals, 2 dedicated helipads */
+/** Intercontinental Airport - 4 runways, 8 terminals, 2 dedicated helipads. */
 static const AirportMovingData _airport_moving_data_intercontinental[77] = {
 	AMD(    8,   87, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar 1
 	AMD(  136,   72, AMED_EXACTPOS,                   DIR_SE), // 01 In Hangar 2
@@ -307,7 +317,7 @@ static const AirportMovingData _airport_moving_data_intercontinental[77] = {
 };
 
 
-/* Heliport (heliport) */
+/** Heliport (heliport). */
 static const AirportMovingData _airport_moving_data_heliport[9] = {
 	AMD(    5,    9, AMED_EXACTPOS,                   DIR_NE), // 0 - At heliport terminal
 	AMD(    2,    9, AMED_HELI_RAISE,                 DIR_N ), // 1 - Take off (play sound)
@@ -320,7 +330,7 @@ static const AirportMovingData _airport_moving_data_heliport[9] = {
 	AMD(   70,    9, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 8 - Circle #4 (south)
 };
 
-/* HeliDepot 2x2 (heliport) */
+/** HeliDepot 2x2 (heliport). */
 static const AirportMovingData _airport_moving_data_helidepot[18] = {
 	AMD(   24,    4, AMED_EXACTPOS,                   DIR_NE), // 0 - At depot
 	AMD(   24,   28, 0,                               DIR_N ), // 1 Taxi to right outside depot
@@ -342,7 +352,7 @@ static const AirportMovingData _airport_moving_data_helidepot[18] = {
 	AMD(    8,   24, AMED_SLOWTURN | AMED_EXACTPOS,   DIR_E ), // 17 - turn on helipad1 for takeoff
 };
 
-/* HeliDepot 2x2 (heliport) */
+/** HeliDepot 2x2 (heliport). */
 static const AirportMovingData _airport_moving_data_helistation[33] = {
 	AMD(    8,    3, AMED_EXACTPOS,                   DIR_SE), // 00 In Hangar2
 	AMD(    8,   22, 0,                               DIR_N ), // 01 outside hangar 2
@@ -379,7 +389,7 @@ static const AirportMovingData _airport_moving_data_helistation[33] = {
 	AMD(  132,  -24, AMED_NOSPDCLAMP | AMED_SLOWTURN, DIR_N ), // 32 Fly around waiting for a landing spot (north-east)
 };
 
-/* Oilrig */
+/** Oilrig. */
 static const AirportMovingData _airport_moving_data_oilrig[9] = {
 	AMD(   31,    9, AMED_EXACTPOS,                   DIR_NE), // 0 - At oilrig terminal
 	AMD(   28,    9, AMED_HELI_RAISE,                 DIR_N ), // 1 - Take off (play sound)
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
index 5a80a9880..2983f76f1 100644
--- a/src/train_cmd.cpp
+++ b/src/train_cmd.cpp
@@ -2810,6 +2810,11 @@ int Train::UpdateSpeed()
 	return scaled_spd;
 }
 
+/**
+ * Trains enters a station, send out a news item if it is the first train, and start loading.
+ * @param v Train that entered the station.
+ * @param station Station visited.
+ */
 static void TrainEnterStation(Train *v, StationID station)
 {
 	v->last_station_visited = station;
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index dc155f9ac..8052a29ac 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -841,6 +841,10 @@ void CallVehicleTicks()
 	cur_company.Restore();
 }
 
+/**
+ * Add vehicle sprite for drawing to the screen.
+ * @param v Vehicle to draw.
+ */
 static void DoDrawVehicle(const Vehicle *v)
 {
 	SpriteID image = v->cur_image;
@@ -1046,6 +1050,10 @@ bool Vehicle::HandleBreakdown()
 	}
 }
 
+/**
+ * Update age of a vehicle.
+ * @param v Vehicle to update.
+ */
 void AgeVehicle(Vehicle *v)
 {
 	if (v->age < MAX_DAY) v->age++;
diff --git a/src/vehicle_base.h b/src/vehicle_base.h
index e9e2ac823..6bd99e10b 100644
--- a/src/vehicle_base.h
+++ b/src/vehicle_base.h
@@ -23,21 +23,23 @@
 #include "transport_type.h"
 #include "group_type.h"
 
+/** Vehicle status bits in #Vehicle::vehstatus. */
 enum VehStatus {
-	VS_HIDDEN          = 0x01,
-	VS_STOPPED         = 0x02,
-	VS_UNCLICKABLE     = 0x04,
-	VS_DEFPAL          = 0x08,
-	VS_TRAIN_SLOWING   = 0x10,
-	VS_SHADOW          = 0x20,
-	VS_AIRCRAFT_BROKEN = 0x40,
-	VS_CRASHED         = 0x80,
+	VS_HIDDEN          = 0x01, ///< Vehicle is not visible.
+	VS_STOPPED         = 0x02, ///< Vehicle is stopped by the player.
+	VS_UNCLICKABLE     = 0x04, ///< Vehicle is not clickable by the user (shadow vehicles).
+	VS_DEFPAL          = 0x08, ///< Use default vehicle palette. @see DoDrawVehicle
+	VS_TRAIN_SLOWING   = 0x10, ///< Train is slowing down.
+	VS_SHADOW          = 0x20, ///< Vehicle is a shadow vehicle.
+	VS_AIRCRAFT_BROKEN = 0x40, ///< Aircraft is broken down.
+	VS_CRASHED         = 0x80, ///< Vehicle is crashed.
 };
 
+/** Bit numbers in #Vehicle::vehicle_flags. */
 enum VehicleFlags {
-	VF_LOADING_FINISHED,
-	VF_CARGO_UNLOADING,
-	VF_BUILT_AS_PROTOTYPE,
+	VF_LOADING_FINISHED,        ///< Vehicle has finished loading.
+	VF_CARGO_UNLOADING,         ///< Vehicle is unloading cargo.
+	VF_BUILT_AS_PROTOTYPE,      ///< Vehicle is a prototype (accepted as exclusive preview).
 	VF_TIMETABLE_STARTED,       ///< Whether the vehicle has started running on the timetable yet.
 	VF_AUTOFILL_TIMETABLE,      ///< Whether the vehicle should fill in the timetable automatically.
 	VF_AUTOFILL_PRES_WAIT_TIME, ///< Whether non-destructive auto-fill should preserve waiting times
@@ -65,6 +67,7 @@ extern bool LoadOldVehicle(LoadgameState *ls, int num);
 extern bool AfterLoadGame();
 extern void FixOldVehicles();
 
+/** Vehicle data structure. */
 struct Vehicle : VehiclePool::PoolItem<&_vehicle_pool>, BaseVehicle {
 private:
 	Vehicle *next;                      ///< pointer to the next vehicle in the chain
@@ -117,10 +120,10 @@ public:
 	Date max_age;                       ///< Maximum age
 	Date date_of_last_service;
 	Date service_interval;
-	uint16 reliability;
-	uint16 reliability_spd_dec;
-	byte breakdown_ctr;
-	byte breakdown_delay;
+	uint16 reliability;                 ///< Reliability.
+	uint16 reliability_spd_dec;         ///< Reliability decrease speed.
+	byte breakdown_ctr;                 ///< Counter for managing breakdown events. @see Vehicle::HandleBreakdown
+	byte breakdown_delay;               ///< Counter for managing breakdown length.
 	byte breakdowns_since_last_service;
 	byte breakdown_chance;
 
diff --git a/src/vehicle_func.h b/src/vehicle_func.h
index 75f44035c..fbca79beb 100644
--- a/src/vehicle_func.h
+++ b/src/vehicle_func.h
@@ -74,6 +74,11 @@ struct GetNewVehiclePosResult {
 GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v);
 Direction GetDirectionTowards(const Vehicle *v, int x, int y);
 
+/**
+ * Is the given vehicle type buildable by a company?
+ * @param type Vehicle type being queried.
+ * @return Vehicle type is buildable by a company.
+ */
 static inline bool IsCompanyBuildableVehicleType(VehicleType type)
 {
 	switch (type) {
@@ -87,6 +92,11 @@ static inline bool IsCompanyBuildableVehicleType(VehicleType type)
 	}
 }
 
+/**
+ * Is the given vehicle buildable by a company?
+ * @param v Vehicle being queried.
+ * @return Vehicle is buildable by a company.
+ */
 static inline bool IsCompanyBuildableVehicleType(const BaseVehicle *v)
 {
 	return IsCompanyBuildableVehicleType(v->type);
diff --git a/src/vehicle_type.h b/src/vehicle_type.h
index 57f55a2b7..3f393435f 100644
--- a/src/vehicle_type.h
+++ b/src/vehicle_type.h
@@ -40,6 +40,7 @@ struct Aircraft;
 struct EffectVehicle;
 struct DisasterVehicle;
 
+/** Base vehicle class. */
 struct BaseVehicle
 {
 	VehicleTypeByte type;    ///< Type of vehicle