Mercurial > hg > openttd
changeset 16372:ea86953aa185 draft
(svn r21088) -Doc: Additions/corrections of doxygen comments.
| author | alberth <alberth@openttd.org> |
|---|---|
| date | Fri, 05 Nov 2010 16:34:22 +0000 |
| parents | f7d156c8ed0d |
| children | 648a04a6ab89 |
| files | src/aircraft.h src/aircraft_cmd.cpp src/airport.cpp src/airport.h src/newgrf_airport.cpp src/roadveh_cmd.cpp src/ship_cmd.cpp src/table/airport_movement.h src/train_cmd.cpp src/vehicle.cpp src/vehicle_base.h src/vehicle_func.h src/vehicle_type.h |
| diffstat | 13 files changed, 258 insertions(+), 121 deletions(-) [+] |
line wrap: on
line diff
--- 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 @@ /** - * 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 @@ * 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 @@ } }; +/** + * Macro for iterating over all aircrafts. + */ #define FOR_ALL_AIRCRAFT(var) FOR_ALL_VEHICLES_OF_TYPE(Aircraft, var) SpriteID GetRotorImage(const Aircraft *v);
--- a/src/aircraft_cmd.cpp +++ b/src/aircraft_cmd.cpp @@ -461,6 +461,13 @@ 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 @@ } /** - * 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 @@ return false; } - +/** + * Handle crashed aircraft \a v. + * @param v Crashed aircraft. + */ static bool HandleCrashedAircraft(Aircraft *v) { v->crashed_counter += 3; @@ -1103,6 +1113,10 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ {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 @@ 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 @@ 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 @@ 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 */
--- 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 @@ * 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 @@ 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;
--- a/src/airport.h +++ b/src/airport.h @@ -26,72 +26,72 @@ /** 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 @@ 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 @@ /** 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 @@ ~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
--- a/src/newgrf_airport.cpp +++ b/src/newgrf_airport.cpp @@ -37,7 +37,7 @@ 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 @@ 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;
--- a/src/roadveh_cmd.cpp +++ b/src/roadveh_cmd.cpp @@ -604,6 +604,11 @@ 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()) {
--- a/src/ship_cmd.cpp +++ b/src/ship_cmd.cpp @@ -317,6 +317,11 @@ 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 */
--- 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ }; -/* 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 @@ 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 @@ 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 @@ 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)
--- a/src/train_cmd.cpp +++ b/src/train_cmd.cpp @@ -2810,6 +2810,11 @@ 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;
--- a/src/vehicle.cpp +++ b/src/vehicle.cpp @@ -841,6 +841,10 @@ 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 @@ } } +/** + * Update age of a vehicle. + * @param v Vehicle to update. + */ void AgeVehicle(Vehicle *v) { if (v->age < MAX_DAY) v->age++;
--- 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 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 @@ 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;
--- a/src/vehicle_func.h +++ b/src/vehicle_func.h @@ -74,6 +74,11 @@ 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 @@ } } +/** + * 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);