summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/aircraft.h25
-rw-r--r--src/aircraft_cmd.cpp75
-rw-r--r--src/airport.cpp19
-rw-r--r--src/airport.h145
-rw-r--r--src/newgrf_airport.cpp4
-rw-r--r--src/roadveh_cmd.cpp5
-rw-r--r--src/ship_cmd.cpp5
-rw-r--r--src/table/airport_movement.h44
-rw-r--r--src/train_cmd.cpp5
-rw-r--r--src/vehicle.cpp8
-rw-r--r--src/vehicle_base.h33
-rw-r--r--src/vehicle_func.h10
-rw-r--r--src/vehicle_type.h1
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