diff options
| -rw-r--r-- | src/object.h | 15 | ||||
| -rw-r--r-- | src/object_base.h | 5 | ||||
| -rw-r--r-- | src/object_cmd.cpp | 20 | ||||
| -rw-r--r-- | src/order_backup.cpp | 51 | ||||
| -rw-r--r-- | src/order_backup.h | 56 | ||||
| -rw-r--r-- | src/order_base.h | 136 | ||||
| -rw-r--r-- | src/order_cmd.cpp | 123 | ||||
| -rw-r--r-- | src/order_func.h | 7 | ||||
| -rw-r--r-- | src/rail.cpp | 31 | ||||
| -rw-r--r-- | src/rail.h | 43 | ||||
| -rw-r--r-- | src/rail_cmd.cpp | 8 | ||||
| -rw-r--r-- | src/rail_map.h | 3 | ||||
| -rw-r--r-- | src/road.cpp | 22 | ||||
| -rw-r--r-- | src/road_func.h | 18 | ||||
| -rw-r--r-- | src/road_internal.h | 11 | ||||
| -rw-r--r-- | src/road_map.cpp | 16 | ||||
| -rw-r--r-- | src/road_map.h | 16 | ||||
| -rw-r--r-- | src/saveload/order_sl.cpp | 4 | ||||
| -rw-r--r-- | src/signs.cpp | 4 | ||||
| -rw-r--r-- | src/signs_base.h | 5 | ||||
| -rw-r--r-- | src/station.cpp | 5 | ||||
| -rw-r--r-- | src/station_base.h | 5 | ||||
| -rw-r--r-- | src/string.cpp | 76 | ||||
| -rw-r--r-- | src/string_func.h | 89 |
24 files changed, 360 insertions, 409 deletions
diff --git a/src/object.h b/src/object.h index 48f9b67c8..e0b0c8eee 100644 --- a/src/object.h +++ b/src/object.h @@ -16,23 +16,8 @@ #include "company_type.h" #include "object_type.h" -/** - * Update the CompanyHQ to the state associated with the given score - * @param tile The (northern) tile of the company HQ, or INVALID_TILE. - * @param score The current (performance) score of the company. - */ void UpdateCompanyHQ(TileIndex tile, uint score); -/** - * Actually build the object. - * @param type The type of object to build. - * @param tile The tile to build the northern tile of the object on. - * @param owner The owner of the object. - * @param town Town the tile is related with. - * @param view The view for the object. - * @pre All preconditions for building the object at that location - * are met, e.g. slope and clearness of tiles are checked. - */ void BuildObject(ObjectType type, TileIndex tile, CompanyID owner = OWNER_NONE, struct Town *town = NULL, uint8 view = 0); void PlaceProc_Object(TileIndex tile); diff --git a/src/object_base.h b/src/object_base.h index a006e16e7..5516d85cc 100644 --- a/src/object_base.h +++ b/src/object_base.h @@ -35,11 +35,6 @@ struct Object : ObjectPool::PoolItem<&_object_pool> { /** Make sure the right destructor is called as well! */ ~Object() {} - /** - * Get the object associated with a tile. - * @param tile The tile to fetch the object for. - * @return The object. - */ static Object *GetByTile(TileIndex tile); /** diff --git a/src/object_cmd.cpp b/src/object_cmd.cpp index 499790579..b8361cdbd 100644 --- a/src/object_cmd.cpp +++ b/src/object_cmd.cpp @@ -43,6 +43,11 @@ ObjectPool _object_pool("Object"); INSTANTIATE_POOL_METHODS(Object) uint16 Object::counts[NUM_OBJECTS]; +/** + * Get the object associated with a tile. + * @param tile The tile to fetch the object for. + * @return The object. + */ /* static */ Object *Object::GetByTile(TileIndex tile) { return Object::Get(GetObjectIndex(tile)); @@ -55,6 +60,16 @@ void InitializeObjects() Object::ResetTypeCounts(); } +/** + * Actually build the object. + * @param type The type of object to build. + * @param tile The tile to build the northern tile of the object on. + * @param owner The owner of the object. + * @param town Town the tile is related with. + * @param view The view for the object. + * @pre All preconditions for building the object at that location + * are met, e.g. slope and clearness of tiles are checked. + */ void BuildObject(ObjectType type, TileIndex tile, CompanyID owner, Town *town, uint8 view) { const ObjectSpec *spec = ObjectSpec::Get(type); @@ -113,6 +128,11 @@ static void IncreaseAnimationStage(TileIndex tile) /** We encode the company HQ size in the animation stage. */ #define IncreaseCompanyHQSize IncreaseAnimationStage +/** + * Update the CompanyHQ to the state associated with the given score + * @param tile The (northern) tile of the company HQ, or INVALID_TILE. + * @param score The current (performance) score of the company. + */ void UpdateCompanyHQ(TileIndex tile, uint score) { if (tile == INVALID_TILE) return; diff --git a/src/order_backup.cpp b/src/order_backup.cpp index b7c4c3312..39f9c5d36 100644 --- a/src/order_backup.cpp +++ b/src/order_backup.cpp @@ -20,6 +20,7 @@ OrderBackupPool _order_backup_pool("BackupOrder"); INSTANTIATE_POOL_METHODS(OrderBackup) +/** Free everything that is allocated. */ OrderBackup::~OrderBackup() { free(this->name); @@ -34,6 +35,11 @@ OrderBackup::~OrderBackup() } } +/** + * Create an order backup for the given vehicle. + * @param v The vehicle to make a backup of. + * @param user The user that is requesting the backup. + */ OrderBackup::OrderBackup(const Vehicle *v, uint32 user) { this->user = user; @@ -62,6 +68,10 @@ OrderBackup::OrderBackup(const Vehicle *v, uint32 user) } } +/** + * Restore the data of this order to the given vehicle. + * @param v The vehicle to restore to. + */ void OrderBackup::DoRestore(Vehicle *v) { /* If we have a custom name, process that */ @@ -84,6 +94,12 @@ void OrderBackup::DoRestore(Vehicle *v) DoCommand(0, this->group, v->index, DC_EXEC, CMD_ADD_VEHICLE_GROUP); } +/** + * Create an order backup for the given vehicle. + * @param v The vehicle to make a backup of. + * @param user The user that is requesting the backup. + * @note Will automatically remove any previous backups of this user. + */ /* static */ void OrderBackup::Backup(const Vehicle *v, uint32 user) { /* Don't use reset as that broadcasts over the network to reset the variable, @@ -95,6 +111,12 @@ void OrderBackup::DoRestore(Vehicle *v) new OrderBackup(v, user); } +/** + * Restore the data of this order to the given vehicle. + * @param v The vehicle to restore to. + * @param user The user that built the vehicle, thus wants to restore. + * @note After restoration the backup will automatically be removed. + */ /* static */ void OrderBackup::Restore(Vehicle *v, uint32 user) { OrderBackup *ob; @@ -106,6 +128,12 @@ void OrderBackup::DoRestore(Vehicle *v) } } +/** + * Reset an OrderBackup given a tile and user. + * @param tile The tile associated with the OrderBackup. + * @param user The user associated with the OrderBackup. + * @note Must not be used from the GUI! + */ /* static */ void OrderBackup::ResetOfUser(TileIndex tile, uint32 user) { OrderBackup *ob; @@ -131,6 +159,12 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1, return CommandCost(); } +/** + * Reset an user's OrderBackup if needed. + * @param user The user associated with the OrderBackup. + * @pre _network_server. + * @note Must not be used from a command. + */ /* static */ void OrderBackup::ResetUser(uint32 user) { assert(_network_server); @@ -145,6 +179,12 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1, } } +/** + * Reset the OrderBackups from GUI/game logic. + * @param tile The tile of the order backup. + * @param from_gui Whether the call came from the GUI, i.e. whether + * it must be synced over the network. + */ /* static */ void OrderBackup::Reset(TileIndex t, bool from_gui) { /* The user has CLIENT_ID_SERVER as default when network play is not active, @@ -177,6 +217,10 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1, } } +/** + * Clear the group of all backups having this group ID. + * @param group The group to clear. + */ /* static */ void OrderBackup::ClearGroup(GroupID group) { OrderBackup *ob; @@ -185,6 +229,13 @@ CommandCost CmdClearOrderBackup(TileIndex tile, DoCommandFlag flags, uint32 p1, } } +/** + * Clear/update the (clone) vehicle from an order backup. + * @param v The vehicle to clear. + * @pre v != NULL + * @note If it is not possible to set another vehicle as clone + * "example", then this backed up order will be removed. + */ /* static */ void OrderBackup::ClearVehicle(const Vehicle *v) { assert(v != NULL); diff --git a/src/order_backup.h b/src/order_backup.h index 3e87b99d9..51281e860 100644 --- a/src/order_backup.h +++ b/src/order_backup.h @@ -51,77 +51,21 @@ private: /** Creation for savegame restoration. */ OrderBackup() {} - - /** - * Create an order backup for the given vehicle. - * @param v The vehicle to make a backup of. - * @param user The user that is requesting the backup. - */ OrderBackup(const Vehicle *v, uint32 user); - /** - * Restore the data of this order to the given vehicle. - * @param v The vehicle to restore to. - */ void DoRestore(Vehicle *v); public: - /** Free everything that is allocated. */ ~OrderBackup(); - /** - * Create an order backup for the given vehicle. - * @param v The vehicle to make a backup of. - * @param user The user that is requesting the backup. - * @note Will automatically remove any previous backups of this user. - */ static void Backup(const Vehicle *v, uint32 user); - - /** - * Restore the data of this order to the given vehicle. - * @param v The vehicle to restore to. - * @param user The user that built the vehicle, thus wants to restore. - * @note After restoration the backup will automatically be removed. - */ static void Restore(Vehicle *v, uint32 user); - /** - * Reset an OrderBackup given a tile and user. - * @param tile The tile associated with the OrderBackup. - * @param user The user associated with the OrderBackup. - * @note Must not be used from the GUI! - */ static void ResetOfUser(TileIndex tile, uint32 user); - - /** - * Reset an user's OrderBackup if needed. - * @param user The user associated with the OrderBackup. - * @pre _network_server. - * @note Must not be used from a command. - */ static void ResetUser(uint32 user); - - /** - * Reset the OrderBackups from GUI/game logic. - * @param tile The tile of the order backup. - * @param from_gui Whether the call came from the GUI, i.e. whether - * it must be synced over the network. - */ static void Reset(TileIndex tile = INVALID_TILE, bool from_gui = true); - /** - * Clear the group of all backups having this group ID. - * @param group The group to clear. - */ static void ClearGroup(GroupID group); - - /** - * Clear/update the (clone) vehicle from an order backup. - * @param v The vehicle to clear. - * @pre v != NULL - * @note If it is not possible to set another vehicle as clone - * "example", then this backed up order will be removed. - */ static void ClearVehicle(const Vehicle *v); }; diff --git a/src/order_base.h b/src/order_base.h index b04ca2b05..44ce7a39d 100644 --- a/src/order_base.h +++ b/src/order_base.h @@ -53,10 +53,6 @@ public: Order() : refit_cargo(CT_NO_REFIT) {} ~Order() {} - /** - * Create an order based on a packed representation of that order. - * @param packed the packed representation. - */ Order(uint32 packed); /** @@ -72,61 +68,15 @@ public: */ inline OrderType GetType() const { return (OrderType)GB(this->type, 0, 4); } - /** - * 'Free' the order - * @note ONLY use on "current_order" vehicle orders! - */ void Free(); - /** - * Makes this order a Go To Station order. - * @param destination the station to go to. - */ void MakeGoToStation(StationID destination); - - /** - * Makes this order a Go To Depot order. - * @param destination the depot to go to. - * @param order is this order a 'default' order, or an overriden vehicle order? - * @param non_stop_type how to get to the depot? - * @param action what to do in the depot? - * @param cargo the cargo type to change to. - * @param subtype the subtype to change to. - */ void MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type = ONSF_NO_STOP_AT_INTERMEDIATE_STATIONS, OrderDepotActionFlags action = ODATF_SERVICE_ONLY, CargoID cargo = CT_NO_REFIT, byte subtype = 0); - - /** - * Makes this order a Go To Waypoint order. - * @param destination the waypoint to go to. - */ void MakeGoToWaypoint(StationID destination); - - /** - * Makes this order a Loading order. - * @param ordered is this an ordered stop? - */ void MakeLoading(bool ordered); - - /** - * Makes this order a Leave Station order. - */ void MakeLeaveStation(); - - /** - * Makes this order a Dummy order. - */ void MakeDummy(); - - /** - * Makes this order an conditional order. - * @param order the order to jump to. - */ void MakeConditional(VehicleOrderID order); - - /** - * Makes this order an automatic order. - * @param destination the station to go to. - */ void MakeAutomatic(StationID destination); /** @@ -164,12 +114,6 @@ public: */ inline byte GetRefitSubtype() const { return this->refit_subtype; } - /** - * Make this depot order also a refit order. - * @param cargo the cargo type to change to. - * @param subtype the subtype to change to. - * @pre IsType(OT_GOTO_DEPOT). - */ void SetRefit(CargoID cargo, byte subtype = 0); /** How must the consist be loaded? */ @@ -225,38 +169,11 @@ public: return true; } - /** - * Assign the given order to this one. - * @param other the data to copy (except next pointer). - */ void AssignOrder(const Order &other); - - /** - * Does this order have the same type, flags and destination? - * @param other the second order to compare to. - * @return true if the type, flags and destination match. - */ bool Equals(const Order &other) const; - /** - * Pack this order into a 32 bits integer, or actually only - * the type, flags and destination. - * @return the packed representation. - * @note unpacking is done in the constructor. - */ uint32 Pack() const; - - /** - * Pack this order into a 16 bits integer as close to the TTD - * representation as possible. - * @return the TTD-like packed representation. - */ uint16 MapOldOrder() const; - - /** - * Converts this order from an old savegame's version; - * it moves all bits to the new location. - */ void ConvertFromOldSavegame(); }; @@ -296,11 +213,6 @@ public: /** Destructor. Invalidates OrderList for re-usage by the pool. */ ~OrderList() {} - /** - * Recomputes everything. - * @param chain first order in the chain - * @param v one of vehicle that is using this orderlist - */ void Initialize(Order *chain, Vehicle *v); /** @@ -309,11 +221,6 @@ public: */ inline Order *GetFirstOrder() const { return this->first; } - /** - * Get a certain order of the order chain. - * @param index zero-based index of the order within the chain. - * @return the order at position index. - */ Order *GetOrderAt(int index) const; /** @@ -334,24 +241,8 @@ public: */ inline VehicleOrderID GetNumManualOrders() const { return this->num_manual_orders; } - /** - * Insert a new order into the order chain. - * @param new_order is the order to insert into the chain. - * @param index is the position where the order is supposed to be inserted. - */ void InsertOrderAt(Order *new_order, int index); - - /** - * Remove an order from the order list and delete it. - * @param index is the position of the order which is to be deleted. - */ void DeleteOrderAt(int index); - - /** - * Move an order to another position within the order list. - * @param from is the zero-based position of the order to move. - * @param to is the zero-based position where the order is moved to. - */ void MoveOrder(int from, int to); /** @@ -372,17 +263,7 @@ public: */ inline uint GetNumVehicles() const { return this->num_vehicles; } - /** - * Checks whether a vehicle is part of the shared vehicle chain. - * @param v is the vehicle to search in the shared vehicle chain. - */ bool IsVehicleInSharedOrdersList(const Vehicle *v) const; - - /** - * Gets the position of the given vehicle within the shared order vehicle list. - * @param v is the vehicle of which to get the position - * @return position of v within the shared vehicle chain. - */ int GetPositionInSharedOrderList(const Vehicle *v) const; /** @@ -393,17 +274,8 @@ public: */ inline void AddVehicle(Vehicle *v) { ++this->num_vehicles; } - /** - * Removes the vehicle from the shared order list. - * @note This is supposed to be called when the vehicle is still in the chain - * @param v vehicle to remove from the list - */ void RemoveVehicle(Vehicle *v); - /** - * Checks whether all orders of the list have a filled timetable. - * @return whether all orders have a filled timetable. - */ bool IsCompleteTimetable() const; /** @@ -424,16 +296,8 @@ public: */ void UpdateOrderTimetable(Ticks delta) { this->timetable_duration += delta; } - /** - * Free a complete order chain. - * @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList. - * @note do not use on "current_order" vehicle orders! - */ void FreeChain(bool keep_orderlist = false); - /** - * Checks for internal consistency of order list. Triggers assertion if something is wrong. - */ void DebugCheckSanity() const; }; diff --git a/src/order_cmd.cpp b/src/order_cmd.cpp index 5d7976a7a..61b1fd5ef 100644 --- a/src/order_cmd.cpp +++ b/src/order_cmd.cpp @@ -42,6 +42,10 @@ INSTANTIATE_POOL_METHODS(Order) OrderListPool _orderlist_pool("OrderList"); INSTANTIATE_POOL_METHODS(OrderList) +/** + * 'Free' the order + * @note ONLY use on "current_order" vehicle orders! + */ void Order::Free() { this->type = OT_NOTHING; @@ -50,6 +54,10 @@ void Order::Free() this->next = NULL; } +/** + * Makes this order a Go To Station order. + * @param destination the station to go to. + */ void Order::MakeGoToStation(StationID destination) { this->type = OT_GOTO_STATION; @@ -57,6 +65,15 @@ void Order::MakeGoToStation(StationID destination) this->dest = destination; } +/** + * Makes this order a Go To Depot order. + * @param destination the depot to go to. + * @param order is this order a 'default' order, or an overriden vehicle order? + * @param non_stop_type how to get to the depot? + * @param action what to do in the depot? + * @param cargo the cargo type to change to. + * @param subtype the subtype to change to. + */ void Order::MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderNonStopFlags non_stop_type, OrderDepotActionFlags action, CargoID cargo, byte subtype) { this->type = OT_GOTO_DEPOT; @@ -67,6 +84,10 @@ void Order::MakeGoToDepot(DepotID destination, OrderDepotTypeFlags order, OrderN this->SetRefit(cargo, subtype); } +/** + * Makes this order a Go To Waypoint order. + * @param destination the waypoint to go to. + */ void Order::MakeGoToWaypoint(StationID destination) { this->type = OT_GOTO_WAYPOINT; @@ -74,24 +95,38 @@ void Order::MakeGoToWaypoint(StationID destination) this->dest = destination; } +/** + * Makes this order a Loading order. + * @param ordered is this an ordered stop? + */ void Order::MakeLoading(bool ordered) { this->type = OT_LOADING; if (!ordered) this->flags = 0; } +/** + * Makes this order a Leave Station order. + */ void Order::MakeLeaveStation() { this->type = OT_LEAVESTATION; this->flags = 0; } +/** + * Makes this order a Dummy order. + */ void Order::MakeDummy() { this->type = OT_DUMMY; this->flags = 0; } +/** + * Makes this order an conditional order. + * @param order the order to jump to. + */ void Order::MakeConditional(VehicleOrderID order) { this->type = OT_CONDITIONAL; @@ -99,18 +134,33 @@ void Order::MakeConditional(VehicleOrderID order) this->dest = 0; } +/** + * Makes this order an automatic order. + * @param destination the station to go to. + */ void Order::MakeAutomatic(StationID destination) { this->type = OT_AUTOMATIC; this->dest = destination; } +/** + * Make this depot order also a refit order. + * @param cargo the cargo type to change to. + * @param subtype the subtype to change to. + * @pre IsType(OT_GOTO_DEPOT). + */ void Order::SetRefit(CargoID cargo, byte subtype) { this->refit_cargo = cargo; this->refit_subtype = subtype; } +/** + * Does this order have the same type, flags and destination? + * @param other the second order to compare to. + * @return true if the type, flags and destination match. + */ bool Order::Equals(const Order &other) const { /* In case of go to nearest depot orders we need "only" compare the flags @@ -128,11 +178,22 @@ bool Order::Equals(const Order &other) const return this->type == other.type && this->flags == other.flags && this->dest == other.dest; } +/** + * Pack this order into a 32 bits integer, or actually only + * the type, flags and destination. + * @return the packed representation. + * @note unpacking is done in the constructor. + */ uint32 Order::Pack() const { return this->dest << 16 | this->flags << 8 | this->type; } +/** + * Pack this order into a 16 bits integer as close to the TTD + * representation as possible. + * @return the TTD-like packed representation. + */ uint16 Order::MapOldOrder() const { uint16 order = this->GetType(); @@ -155,6 +216,10 @@ uint16 Order::MapOldOrder() const return order; } +/** + * Create an order based on a packed representation of that order. + * @param packed the packed representation. + */ Order::Order(uint32 packed) { this->type = (OrderType)GB(packed, 0, 8); @@ -191,6 +256,7 @@ void InvalidateVehicleOrder(const Vehicle *v, int data) * * Assign data to an order (from another order) * This function makes sure that the index is maintained correctly + * @param other the data to copy (except next pointer). * */ void Order::AssignOrder(const Order &other) @@ -206,6 +272,11 @@ void Order::AssignOrder(const Order &other) this->travel_time = other.travel_time; } +/** + * Recomputes everything. + * @param chain first order in the chain + * @param v one of vehicle that is using this orderlist + */ void OrderList::Initialize(Order *chain, Vehicle *v) { this->first = chain; @@ -230,6 +301,11 @@ void OrderList::Initialize(Order *chain, Vehicle *v) for (const Vehicle *u = v->NextShared(); u != NULL; u = u->NextShared()) ++this->num_vehicles; } +/** + * Free a complete order chain. + * @param keep_orderlist If this is true only delete the orders, otherwise also delete the OrderList. + * @note do not use on "current_order" vehicle orders! + */ void OrderList::FreeChain(bool keep_orderlist) { Order *next; @@ -248,6 +324,11 @@ void OrderList::FreeChain(bool keep_orderlist) } } +/** + * Get a certain order of the order chain. + * @param index zero-based index of the order within the chain. + * @return the order at position index. + */ Order *OrderList::GetOrderAt(int index) const { if (index < 0) return NULL; @@ -260,6 +341,11 @@ Order *OrderList::GetOrderAt(int index) const return order; } +/** + * Insert a new order into the order chain. + * @param new_order is the order to insert into the chain. + * @param index is the position where the order is supposed to be inserted. + */ void OrderList::InsertOrderAt(Order *new_order, int index) { if (this->first == NULL) { @@ -285,6 +371,10 @@ void OrderList::InsertOrderAt(Order *new_order, int index) } +/** + * Remove an order from the order list and delete it. + * @param index is the position of the order which is to be deleted. + */ void OrderList::DeleteOrderAt(int index) { if (index >= this->num_orders) return; @@ -305,6 +395,11 @@ void OrderList::DeleteOrderAt(int index) delete to_remove; } +/** + * Move an order to another position within the order list. + * @param from is the zero-based position of the order to move. + * @param to is the zero-based position where the order is moved to. + */ void OrderList::MoveOrder(int from, int to) { if (from >= this->num_orders || to >= this->num_orders || from == to) return; @@ -332,12 +427,21 @@ void OrderList::MoveOrder(int from, int to) } } +/** + * Removes the vehicle from the shared order list. + * @note This is supposed to be called when the vehicle is still in the chain + * @param v vehicle to remove from the list + */ void OrderList::RemoveVehicle(Vehicle *v) { --this->num_vehicles; if (v == this->first_shared) this->first_shared = v->NextShared(); } +/** + * Checks whether a vehicle is part of the shared vehicle chain. + * @param v is the vehicle to search in the shared vehicle chain. + */ bool OrderList::IsVehicleInSharedOrdersList(const Vehicle *v) const { for (const Vehicle *v_shared = this->first_shared; v_shared != NULL; v_shared = v_shared->NextShared()) { @@ -347,6 +451,11 @@ bool OrderList::IsVehicleInSharedOrdersList(const Vehicle *v) const return false; } +/** + * Gets the position of the given vehicle within the shared order vehicle list. + * @param v is the vehicle of which to get the position + * @return position of v within the shared vehicle chain. + */ int OrderList::GetPositionInSharedOrderList(const Vehicle *v) const { int count = 0; @@ -354,6 +463,10 @@ int OrderList::GetPositionInSharedOrderList(const Vehicle *v) const return count; } +/** + * Checks whether all orders of the list have a filled timetable. + * @return whether all orders have a filled timetable. + */ bool OrderList::IsCompleteTimetable() const { for (Order *o = this->first; o != NULL; o = o->next) { @@ -364,6 +477,9 @@ bool OrderList::IsCompleteTimetable() const return true; } +/** + * Checks for internal consistency of order list. Triggers assertion if something is wrong. + */ void OrderList::DebugCheckSanity() const { VehicleOrderID check_num_orders = 0; @@ -1524,6 +1640,13 @@ void DeleteVehicleOrders(Vehicle *v, bool keep_orderlist) } } +/** + * Clamp the service interval to the correct min/max. The actual min/max values + * depend on whether it's in percent or days. + * @param interval proposed service interval + * @param company_id the owner of the vehicle + * @return Clamped service interval + */ uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id) { return (Company::Get(company_id)->settings.vehicle.servint_ispercent) ? Clamp(interval, MIN_SERVINT_PERCENT, MAX_SERVINT_PERCENT) : Clamp(interval, MIN_SERVINT_DAYS, MAX_SERVINT_DAYS); diff --git a/src/order_func.h b/src/order_func.h index 638c940af..235f9cdc9 100644 --- a/src/order_func.h +++ b/src/order_func.h @@ -32,13 +32,6 @@ void DrawOrderString(const Vehicle *v, const Order *order, int order_index, int #define MIN_SERVINT_DAYS 30 #define MAX_SERVINT_DAYS 800 -/** - * Clamp the service interval to the correct min/max. The actual min/max values - * depend on whether it's in percent or days. - * @param interval proposed service interval - * @param company_id the owner of the vehicle - * @return Clamped service interval - */ uint16 GetServiceIntervalClamped(uint interval, CompanyID company_id); #endif /* ORDER_FUNC_H */ diff --git a/src/rail.cpp b/src/rail.cpp index 2a308c547..13346d607 100644 --- a/src/rail.cpp +++ b/src/rail.cpp @@ -149,6 +149,9 @@ extern const TrackdirBits _uphill_trackdirs[] = { TRACKDIR_BIT_X_NE | TRACKDIR_BIT_Y_SE, ///< 30 SLOPE_STEEP_E -> inclined for diagonal track }; +/** + * Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile. + */ RailType GetTileRailType(TileIndex tile) { switch (GetTileType(tile)) { @@ -174,16 +177,34 @@ RailType GetTileRailType(TileIndex tile) return INVALID_RAILTYPE; } +/** + * Finds out if a company has a certain railtype available + * @param company the company in question + * @param railtype requested RailType + * @return true if company has requested RailType available + */ bool HasRailtypeAvail(const CompanyID company, const RailType railtype) { return HasBit(Company::Get(company)->avail_railtypes, railtype); } +/** + * Validate functions for rail building. + * @param rail the railtype to check. + * @return true if the current company may build the rail. + */ bool ValParamRailtype(const RailType rail) { return rail < RAILTYPE_END && HasRailtypeAvail(_current_company, rail); } +/** + * Returns the "best" railtype a company can build. + * As the AI doesn't know what the BEST one is, we have our own priority list + * here. When adding new railtypes, modify this function + * @param company the company "in action" + * @return The "best" railtype a company has available + */ RailType GetBestRailtype(const CompanyID company) { if (HasRailtypeAvail(company, RAILTYPE_MAGLEV)) return RAILTYPE_MAGLEV; @@ -226,6 +247,11 @@ RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date) return rts == current ? rts : AddDateIntroducedRailTypes(rts, date); } +/** + * Get the rail types the given company can build. + * @param c the company to get the rail types for. + * @return the rail types. + */ RailTypes GetCompanyRailtypes(CompanyID company) { RailTypes rts = RAILTYPES_NONE; @@ -248,6 +274,11 @@ RailTypes GetCompanyRailtypes(CompanyID company) return AddDateIntroducedRailTypes(rts, _date); } +/** + * Get the rail type for a given label. + * @param label the railtype label. + * @return the railtype. + */ RailType GetRailTypeByLabel(RailTypeLabel label) { /* Loop through each rail type until the label is found */ diff --git a/src/rail.h b/src/rail.h index 46df36803..20260d241 100644 --- a/src/rail.h +++ b/src/rail.h @@ -360,59 +360,18 @@ int TicksToLeaveDepot(const Train *v); Foundation GetRailFoundation(Slope tileh, TrackBits bits); -/** - * Finds out if a company has a certain railtype available - * @param company the company in question - * @param railtype requested RailType - * @return true if company has requested RailType available - */ bool HasRailtypeAvail(const CompanyID company, const RailType railtype); - -/** - * Validate functions for rail building. - * @param rail the railtype to check. - * @return true if the current company may build the rail. - */ bool ValParamRailtype(const RailType rail); -/** - * Returns the "best" railtype a company can build. - * As the AI doesn't know what the BEST one is, we have our own priority list - * here. When adding new railtypes, modify this function - * @param company the company "in action" - * @return The "best" railtype a company has available - */ -RailType GetBestRailtype(const CompanyID company); - RailTypes AddDateIntroducedRailTypes(RailTypes current, Date date); -/** - * Get the rail types the given company can build. - * @param c the company to get the rail types for. - * @return the rail types. - */ +RailType GetBestRailtype(const CompanyID company); RailTypes GetCompanyRailtypes(const CompanyID c); -/** - * Get the rail type for a given label. - * @param label the railtype label. - * @return the railtype. - */ RailType GetRailTypeByLabel(RailTypeLabel label); -/** - * Reset all rail type information to its default values. - */ void ResetRailTypes(); - -/** - * Resolve sprites of custom rail types - */ void InitRailTypes(); - -/** - * Allocate a new rail type label - */ RailType AllocateRailType(RailTypeLabel label); #endif /* RAIL_H */ diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp index be056ed4b..508ba8459 100644 --- a/src/rail_cmd.cpp +++ b/src/rail_cmd.cpp @@ -45,7 +45,7 @@ RailtypeInfo _railtypes[RAILTYPE_END]; assert_compile(sizeof(_original_railtypes) <= sizeof(_railtypes)); /** - * Initialize rail type information. + * Reset all rail type information to its default values. */ void ResetRailTypes() { @@ -76,6 +76,9 @@ void ResolveRailTypeGUISprites(RailtypeInfo *rti) } } +/** + * Resolve sprites of custom rail types + */ void InitRailTypes() { for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) { @@ -84,6 +87,9 @@ void InitRailTypes() } } +/** + * Allocate a new rail type label + */ RailType AllocateRailType(RailTypeLabel label) { for (RailType rt = RAILTYPE_BEGIN; rt != RAILTYPE_END; rt++) { diff --git a/src/rail_map.h b/src/rail_map.h index 59a1feeda..bdd4dadfd 100644 --- a/src/rail_map.h +++ b/src/rail_map.h @@ -490,9 +490,6 @@ static inline bool HasOnewaySignalBlockingTrackdir(TileIndex tile, Trackdir td) } -/** - * Return the rail type of tile, or INVALID_RAILTYPE if this is no rail tile. - */ RailType GetTileRailType(TileIndex tile); /** The ground 'under' the rail */ diff --git a/src/road.cpp b/src/road.cpp index 4142f0bfa..dd5641823 100644 --- a/src/road.cpp +++ b/src/road.cpp @@ -36,6 +36,12 @@ static bool IsPossibleCrossing(const TileIndex tile, Axis ax) GetFoundationSlope(tile, NULL) == SLOPE_FLAT); } +/** + * Clean up unneccesary RoadBits of a planed tile. + * @param tile current tile + * @param org_rb planed RoadBits + * @return optimised RoadBits + */ RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb) { if (!IsValidTile(tile)) return ROAD_NONE; @@ -91,6 +97,12 @@ RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb) return org_rb; } +/** + * Finds out, whether given company has all given RoadTypes available + * @param company ID of company + * @param rts RoadTypes to test + * @return true if company has all requested RoadTypes available + */ bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts) { RoadTypes avail_roadtypes; @@ -105,11 +117,21 @@ bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts) return (rts & ~avail_roadtypes) == 0; } +/** + * Validate functions for rail building. + * @param rt road type to check. + * @return true if the current company may build the road. + */ bool ValParamRoadType(const RoadType rt) { return HasRoadTypesAvail(_current_company, RoadTypeToRoadTypes(rt)); } +/** + * Get the road types the given company can build. + * @param company the company to get the roadtypes for. + * @return the road types. + */ RoadTypes GetCompanyRoadtypes(CompanyID company) { RoadTypes rt = ROADTYPES_NONE; diff --git a/src/road_func.h b/src/road_func.h index 4a49d4601..2f286730f 100644 --- a/src/road_func.h +++ b/src/road_func.h @@ -148,26 +148,8 @@ static inline RoadBits AxisToRoadBits(Axis a) return a == AXIS_X ? ROAD_X : ROAD_Y; } -/** - * Finds out, whether given company has all given RoadTypes available - * @param company ID of company - * @param rts RoadTypes to test - * @return true if company has all requested RoadTypes available - */ bool HasRoadTypesAvail(const CompanyID company, const RoadTypes rts); - -/** - * Validate functions for rail building. - * @param rt road type to check. - * @return true if the current company may build the road. - */ bool ValParamRoadType(const RoadType rt); - -/** - * Get the road types the given company can build. - * @param company the company to get the roadtypes for. - * @return the road types. - */ RoadTypes GetCompanyRoadtypes(const CompanyID company); void UpdateLevelCrossing(TileIndex tile, bool sound = true); diff --git a/src/road_internal.h b/src/road_internal.h index 0a6c02202..c8cae8422 100644 --- a/src/road_internal.h +++ b/src/road_internal.h @@ -15,21 +15,10 @@ #include "tile_cmd.h" #include "road_type.h" -/** - * Clean up unneccesary RoadBits of a planed tile. - * @param tile current tile - * @param org_rb planed RoadBits - * @return optimised RoadBits - */ RoadBits CleanUpRoadBits(const TileIndex tile, RoadBits org_rb); CommandCost CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, Owner owner, RoadType rt, DoCommandFlag flags, bool town_check = true); -/** - * Draw the catenary for tram road bits - * @param ti information about the tile (position, slope) - * @param tram the roadbits to draw the catenary for - */ void DrawTramCatenary(const TileInfo *ti, RoadBits tram); #endif /* ROAD_INTERNAL_H */ diff --git a/src/road_map.cpp b/src/road_map.cpp index e995f17f2..2c24582ee 100644 --- a/src/road_map.cpp +++ b/src/road_map.cpp @@ -14,6 +14,22 @@ #include "tunnelbridge_map.h" +/** + * Returns the RoadBits on an arbitrary tile + * Special behaviour: + * - road depots: entrance is treated as road piece + * - road tunnels: entrance is treated as road piece + * - bridge ramps: start of the ramp is treated as road piece + * - bridge middle parts: bridge itself is ignored + * + * If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y + * for bridge ramps and tunnel entrances is returned depending + * on the orientation of the tunnel or bridge. + * @param tile the tile to get the road bits for + * @param rt the road type to get the road bits form + * @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges. + * @return the road bits of the given tile + */ RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance) { if (!HasTileRoadType(tile, rt)) return ROAD_NONE; diff --git a/src/road_map.h b/src/road_map.h index e3fce5893..01daba8e7 100644 --- a/src/road_map.h +++ b/src/road_map.h @@ -536,22 +536,6 @@ static inline DiagDirection GetRoadDepotDirection(TileIndex t) } -/** - * Returns the RoadBits on an arbitrary tile - * Special behaviour: - * - road depots: entrance is treated as road piece - * - road tunnels: entrance is treated as road piece - * - bridge ramps: start of the ramp is treated as road piece - * - bridge middle parts: bridge itself is ignored - * - * If straight_tunnel_bridge_entrance is set a ROAD_X or ROAD_Y - * for bridge ramps and tunnel entrances is returned depending - * on the orientation of the tunnel or bridge. - * @param tile the tile to get the road bits for - * @param rt the road type to get the road bits form - * @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges. - * @return the road bits of the given tile - */ RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance = false); diff --git a/src/saveload/order_sl.cpp b/src/saveload/order_sl.cpp index 31c6c9fb8..f9fd46231 100644 --- a/src/saveload/order_sl.cpp +++ b/src/saveload/order_sl.cpp @@ -17,6 +17,10 @@ #include "saveload.h" +/** + * Converts this order from an old savegame's version; + * it moves all bits to the new location. + */ void Order::ConvertFromOldSavegame() { uint8 old_flags = this->flags; diff --git a/src/signs.cpp b/src/signs.cpp index a86d79e9f..536644bf9 100644 --- a/src/signs.cpp +++ b/src/signs.cpp @@ -22,11 +22,15 @@ SignPool _sign_pool("Sign"); INSTANTIATE_POOL_METHODS(Sign) +/** + * Creates a new sign + */ Sign::Sign(Owner owner) { this->owner = owner; } +/** Destroy the sign */ Sign::~Sign() { free(this->name); diff --git a/src/signs_base.h b/src/signs_base.h index 548e9b837..2c4ec83f1 100644 --- a/src/signs_base.h +++ b/src/signs_base.h @@ -28,12 +28,7 @@ struct Sign : SignPool::PoolItem<&_sign_pool> { byte z; OwnerByte owner; // placed by this company. Anyone can delete them though. OWNER_NONE for gray signs from old games. - /** - * Creates a new sign - */ Sign(Owner owner = INVALID_OWNER); - - /** Destroy the sign */ ~Sign(); void UpdateVirtCoord(); diff --git a/src/station.cpp b/src/station.cpp index 003798a8f..cafdf51f2 100644 --- a/src/station.cpp +++ b/src/station.cpp @@ -155,6 +155,11 @@ void Station::AddFacility(StationFacility new_facility_bit, TileIndex facil_xy) this->build_date = _date; } +/** + * Marks the tiles of the station as dirty. + * + * @ingroup dirty + */ void Station::MarkTilesDirty(bool cargo_change) const { TileIndex tile = this->train_station.tile; diff --git a/src/station_base.h b/src/station_base.h index d595379e9..7d64664dd 100644 --- a/src/station_base.h +++ b/src/station_base.h @@ -199,11 +199,6 @@ public: void AddFacility(StationFacility new_facility_bit, TileIndex facil_xy); - /** - * Marks the tiles of the station as dirty. - * - * @ingroup dirty - */ void MarkTilesDirty(bool cargo_change) const; void UpdateVirtCoord(); diff --git a/src/string.cpp b/src/string.cpp index 9d75e5c65..46ed9e9d7 100644 --- a/src/string.cpp +++ b/src/string.cpp @@ -48,6 +48,20 @@ static int CDECL vseprintf(char *str, const char *last, const char *format, va_l return min((int)diff, vsnprintf(str, diff + 1, format, ap)); } +/** + * Appends characters from one string to another. + * + * Appends the source string to the destination string with respect of the + * terminating null-character and the maximum size of the destination + * buffer. + * + * @note usage ttd_strlcat(dst, src, lengthof(dst)); + * @note lengthof() applies only to fixed size arrays + * + * @param dst The buffer containing the target string + * @param src The buffer containing the string to append + * @param size The maximum size of the destination buffer + */ void ttd_strlcat(char *dst, const char *src, size_t size) { assert(size > 0); @@ -60,6 +74,20 @@ void ttd_strlcat(char *dst, const char *src, size_t size) } +/** + * Copies characters from one buffer to another. + * + * Copies the source string to the destination buffer with respect of the + * terminating null-character and the maximum size of the destination + * buffer. + * + * @note usage ttd_strlcpy(dst, src, lengthof(dst)); + * @note lengthof() applies only to fixed size arrays + * + * @param dst The destination buffer + * @param src The buffer containing the string to copy + * @param size The maximum size of the destination buffer + */ void ttd_strlcpy(char *dst, const char *src, size_t size) { assert(size > 0); @@ -70,6 +98,22 @@ void ttd_strlcpy(char *dst, const char *src, size_t size) } +/** + * Appends characters from one string to another. + * + * Appends the source string to the destination string with respect of the + * terminating null-character and and the last pointer to the last element + * in the destination buffer. If the last pointer is set to NULL no + * boundary check is performed. + * + * @note usage: strecat(dst, src, lastof(dst)); + * @note lastof() applies only to fixed size arrays + * + * @param dst The buffer containing the target string + * @param src The buffer containing the string to append + * @param last The pointer to the last element of the destination buffer + * @return The pointer to the terminating null-character in the destination buffer + */ char *strecat(char *dst, const char *src, const char *last) { assert(dst <= last); @@ -82,6 +126,22 @@ char *strecat(char *dst, const char *src, const char *last) } +/** + * Copies characters from one buffer to another. + * + * Copies the source string to the destination buffer with respect of the + * terminating null-character and the last pointer to the last element in + * the destination buffer. If the last pointer is set to NULL no boundary + * check is performed. + * + * @note usage: strecpy(dst, src, lastof(dst)); + * @note lastof() applies only to fixed size arrays + * + * @param dst The destination buffer + * @param src The buffer containing the string to copy + * @param last The pointer to the last element of the destination buffer + * @return The pointer to the terminating null-character in the destination buffer + */ char *strecpy(char *dst, const char *src, const char *last) { assert(dst <= last); @@ -115,6 +175,14 @@ char *CDECL str_fmt(const char *str, ...) } +/** + * Scans the string for valid characters and if it finds invalid ones, + * replaces them with a question mark '?' (if not ignored) + * @param str the string to validate + * @param last the last valid character of str + * @param allow_newlines whether newlines should be allowed or ignored + * @param ignore whether to ignore or replace with a question mark + */ void str_validate(char *str, const char *last, bool allow_newlines, bool ignore) { /* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */ @@ -169,6 +237,13 @@ void str_validate(char *str, const char *last, bool allow_newlines, bool ignore) *dst = '\0'; } +/** + * Checks whether the given string is valid, i.e. contains only + * valid (printable) characters and is properly terminated. + * @param str The string to validate. + * @param last The last character of the string, i.e. the string + * must be terminated here or earlier. + */ bool StrValid(const char *str, const char *last) { /* Assume the ABSOLUTE WORST to be in str as it comes from the outside. */ @@ -193,6 +268,7 @@ bool StrValid(const char *str, const char *last) return *str == '\0'; } +/** Scans the string for colour codes and strips them */ void str_strip_colours(char *str) { char *dst = str; diff --git a/src/string_func.h b/src/string_func.h index fe3d16971..27cff81f7 100644 --- a/src/string_func.h +++ b/src/string_func.h @@ -29,101 +29,20 @@ #include "core/bitmath_func.hpp" #include "string_type.h" -/** - * Appends characters from one string to another. - * - * Appends the source string to the destination string with respect of the - * terminating null-character and the maximum size of the destination - * buffer. - * - * @note usage ttd_strlcat(dst, src, lengthof(dst)); - * @note lengthof() applies only to fixed size arrays - * - * @param dst The buffer containing the target string - * @param src The buffer containing the string to append - * @param size The maximum size of the destination buffer - */ void ttd_strlcat(char *dst, const char *src, size_t size); - -/** - * Copies characters from one buffer to another. - * - * Copies the source string to the destination buffer with respect of the - * terminating null-character and the maximum size of the destination - * buffer. - * - * @note usage ttd_strlcpy(dst, src, lengthof(dst)); - * @note lengthof() applies only to fixed size arrays - * - * @param dst The destination buffer - * @param src The buffer containing the string to copy - * @param size The maximum size of the destination buffer - */ void ttd_strlcpy(char *dst, const char *src, size_t size); -/** - * Appends characters from one string to another. - * - * Appends the source string to the destination string with respect of the - * terminating null-character and and the last pointer to the last element - * in the destination buffer. If the last pointer is set to NULL no - * boundary check is performed. - * - * @note usage: strecat(dst, src, lastof(dst)); - * @note lastof() applies only to fixed size arrays - * - * @param dst The buffer containing the target string - * @param src The buffer containing the string to append - * @param last The pointer to the last element of the destination buffer - * @return The pointer to the terminating null-character in the destination buffer - */ char *strecat(char *dst, const char *src, const char *last); - -/** - * Copies characters from one buffer to another. - * - * Copies the source string to the destination buffer with respect of the - * terminating null-character and the last pointer to the last element in - * the destination buffer. If the last pointer is set to NULL no boundary - * check is performed. - * - * @note usage: strecpy(dst, src, lastof(dst)); - * @note lastof() applies only to fixed size arrays - * - * @param dst The destination buffer - * @param src The buffer containing the string to copy - * @param last The pointer to the last element of the destination buffer - * @return The pointer to the terminating null-character in the destination buffer - */ char *strecpy(char *dst, const char *src, const char *last); int CDECL seprintf(char *str, const char *last, const char *format, ...) WARN_FORMAT(3, 4); char *CDECL str_fmt(const char *str, ...) WARN_FORMAT(1, 2); -/** - * Scans the string for valid characters and if it finds invalid ones, - * replaces them with a question mark '?' (if not ignored) - * @param str the string to validate - * @param last the last valid character of str - * @param allow_newlines whether newlines should be allowed or ignored - * @param ignore whether to ignore or replace with a question mark - */ void str_validate(char *str, const char *last, bool allow_newlines = false, bool ignore = false); - -/** Scans the string for colour codes and strips them */ void str_strip_colours(char *str); - -/** Convert the given string to lowercase, only works with ASCII! */ void strtolower(char *str); -/** - * Checks whether the given string is valid, i.e. contains only - * valid (printable) characters and is properly terminated. - * @param str The string to validate. - * @param last The last character of the string, i.e. the string - * must be terminated here or earlier. - */ bool StrValid(const char *str, const char *last); /** @@ -152,16 +71,8 @@ static inline size_t ttd_strnlen(const char *str, size_t maxlen) return t - str; } -/** Convert the md5sum number to a 'hexadecimal' string, return next pos in buffer */ char *md5sumToString(char *buf, const char *last, const uint8 md5sum[16]); -/** - * Only allow certain keys. You can define the filter to be used. This makes - * sure no invalid keys can get into an editbox, like BELL. - * @param key character to be checked - * @param afilter the filter to use - * @return true or false depending if the character is printable/valid or not - */ bool IsValidChar(WChar key, CharSetFilter afilter); size_t Utf8Decode(WChar *c, const char *s); |