(svn r12504) [NoAI] -Documentation: the last few files which now are consistent in their comments (anyway, so I hope :))
--- a/src/ai/api/ai_bridge.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_bridge.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -95,7 +95,7 @@
* @pre 'start' and 'end' are in a straight line, i.e.
* AIMap::GetTileX(start) == AIMap::GetTileX(end) or
* AIMap::GetTileY(start) == AIMap::GetTileY(end).
- * @pre VehicleType is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
+ * @pre 'vehicle_type' is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
* @return Whether the bridge has been/can be build or not.
*/
static bool BuildBridge(AIVehicle::VehicleType vehicle_type, BridgeID bridge_id, TileIndex start, TileIndex end);
--- a/src/ai/api/ai_order.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_order.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -40,99 +40,99 @@
/**
* Checks whether the given order id is valid for the given vehicle.
- * @param vehicle_id the vehicle to check the order index for.
- * @param order_id the order index to check.
+ * @param vehicle_id The vehicle to check the order index for.
+ * @param order_id The order index to check.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
- * @return true if and only if the order_id is valid for the given vehicle.
+ * @return True if and only if the order_id is valid for the given vehicle.
*/
static bool IsValidVehicleOrder(VehicleID vehicle_id, uint32 order_id);
/**
* Checks whether the given order flags are valid for the given destination.
- * @param destination the destination of the order.
- * @param order_flags the flags given to the order.
- * @return true if and only if the order_flags are valid for the given location.
+ * @param destination The destination of the order.
+ * @param order_flags The flags given to the order.
+ * @return True if and only if the order_flags are valid for the given location.
*/
static bool AreOrderFlagsValid(TileIndex destination, AIOrderFlags order_flags);
/**
* Returns the number of orders for the given vehicle.
- * @param vehicle_id the vehicle to get the order count of.
+ * @param vehicle_id The vehicle to get the order count of.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
- * @return the number of orders for the given vehicle or a negative
+ * @return The number of orders for the given vehicle or a negative
* value when the vehicle does not exist.
*/
static int32 GetNumberOfOrders(VehicleID vehicle_id);
/**
* Gets the destination of the given order for the given vehicle.
- * @param vehicle_id the vehicle to get the destination for.
- * @param order_id the order to get the destination for.
+ * @param vehicle_id The vehicle to get the destination for.
+ * @param order_id The order to get the destination for.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
- * @return the destination tile of the order.
+ * @return The destination tile of the order.
*/
static TileIndex GetOrderDestination(VehicleID vehicle_id, uint32 order_id);
/**
* Gets the AIOrderFlags of the given order for the given vehicle.
- * @param vehicle_id the vehicle to get the destination for.
- * @param order_id the order to get the destination for.
+ * @param vehicle_id The vehicle to get the destination for.
+ * @param order_id The order to get the destination for.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
- * @return the AIOrderFlags of the order.
+ * @return The AIOrderFlags of the order.
*/
static AIOrderFlags GetOrderFlags(VehicleID vehicle_id, uint32 order_id);
/**
* Appends an order to the end of the vehicle's order list.
- * @param vehicle_id the vehicle to append the order to.
- * @param destination the destination of the order.
- * @param order_flags the flags given to the order.
+ * @param vehicle_id The vehicle to append the order to.
+ * @param destination The destination of the order.
+ * @param order_flags The flags given to the order.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AreOrderFlagsValid(destination, order_flags).
- * @return true if and only if the order was appended.
+ * @return True if and only if the order was appended.
*/
static bool AppendOrder(VehicleID vehicle_id, TileIndex destination, AIOrderFlags order_flags);
/**
* Inserts an order before the given order_id into the vehicle's order list.
- * @param vehicle_id the vehicle to add the order to.
- * @param order_id the order to place the new order before.
- * @param destination the destination of the order.
- * @param order_flags the flags given to the order.
+ * @param vehicle_id The vehicle to add the order to.
+ * @param order_id The order to place the new order before.
+ * @param destination The destination of the order.
+ * @param order_flags The flags given to the order.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @pre AreOrderFlagsValid(destination, order_flags).
- * @return true if and only if the order was inserted.
+ * @return True if and only if the order was inserted.
*/
static bool InsertOrder(VehicleID vehicle_id, uint32 order_id, TileIndex destination, AIOrderFlags order_flags);
/**
* Removes an order from the vehicle's order list.
- * @param vehicle_id the vehicle to remove the order from.
- * @param order_id the order to remove from the order list.
+ * @param vehicle_id The vehicle to remove the order from.
+ * @param order_id The order to remove from the order list.
* @pre AIVehicle::IsValidVehicleOrder(vehicle_id, order_id).
- * @return true if and only if the order was removed.
+ * @return True if and only if the order was removed.
*/
static bool RemoveOrder(VehicleID vehicle_id, uint32 order_id);
/**
* Changes the order flags of the given order.
- * @param vehicle_id the vehicle to change the order of.
- * @param order_id the order to change.
- * @param order_flags the new flags given to the order.
+ * @param vehicle_id The vehicle to change the order of.
+ * @param order_id The order to change.
+ * @param order_flags The new flags given to the order.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
* @pre AreOrderFlagsValid(GetOrderDestination(vehicle_id, order_id), order_flags).
- * @return true if and only if the order was changed.
+ * @return True if and only if the order was changed.
*/
static bool ChangeOrder(VehicleID vehicle_id, uint32 order_id, AIOrderFlags order_flags);
/**
* Move an order inside the orderlist
- * @param vehicle_id the vehicle to move the orders.
- * @param order_id_move the order to move.
- * @param order_id_target the target order
+ * @param vehicle_id The vehicle to move the orders.
+ * @param order_id_move The order to move.
+ * @param order_id_target The target order
* @pre IsValidVehicleOrder(vehicle_id, order_id_move).
* @pre IsValidVehicleOrder(vehicle_id, order_id_target).
- * @return true if and only if the order was moved.
+ * @return True if and only if the order was moved.
* @note If the order is moved to a lower place (e.g. from 7 to 2)
* the target order is moved upwards (e.g. 3). If the order is moved
* to a higher place (e.g. from 7 to 9) the target will be moved
@@ -141,32 +141,32 @@
static bool MoveOrder(VehicleID vehicle_id, uint32 order_id_move, uint32 order_id_target);
/**
- * Copies the orders from another vehicle. The orders of the main
- * vehicle are going to be the orders of the changed vehicle.
- * @param vehicle_id the vehicle to copy the orders to.
- * @param main_vehicle_id the vehicle to copy the orders from.
+ * Copies the orders from another vehicle. The orders of the main vehicle
+ * are going to be the orders of the changed vehicle.
+ * @param vehicle_id The vehicle to copy the orders to.
+ * @param main_vehicle_id The vehicle to copy the orders from.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
- * @return true if and only if the copying succeeded.
+ * @return True if and only if the copying succeeded.
*/
static bool CopyOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
/**
* Shares the orders between two vehicles. The orders of the main
* vehicle are going to be the orders of the changed vehicle.
- * @param vehicle_id the vehicle to add to the shared order list.
- * @param main_vehicle_id the vehicle to share the orders with.
+ * @param vehicle_id The vehicle to add to the shared order list.
+ * @param main_vehicle_id The vehicle to share the orders with.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
* @pre AIVehicle::IsValidVehicle(main_vehicle_id).
- * @return true if and only if the sharing succeeded.
+ * @return True if and only if the sharing succeeded.
*/
static bool ShareOrders(VehicleID vehicle_id, VehicleID main_vehicle_id);
/**
* Removes the given vehicle from a shared orders list.
- * @param vehicle_id the vehicle to remove from the shared order list.
+ * @param vehicle_id The vehicle to remove from the shared order list.
* @pre AIVehicle::IsValidVehicle(vehicle_id).
- * @return true if and only if the unsharing succeeded.
+ * @return True if and only if the unsharing succeeded.
*/
static bool UnshareOrders(VehicleID vehicle_id);
};
--- a/src/ai/api/ai_road.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_road.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -15,56 +15,56 @@
static const char *GetClassName() { return "AIRoad"; }
/**
- * Checks whether the given tile is actually a tile with road that
- * can be used to traverse a tile. This excludes road depots and
- * 'normal' road stations, but includes drive through stations.
- * @param tile the tile to check.
+ * Checks whether the given tile is actually a tile with road that can be
+ * used to traverse a tile. This excludes road depots and 'normal' road
+ * stations, but includes drive through stations.
+ * @param tile The tile to check.
* @pre AIMap::IsValidTile(tile).
- * @return true if and only if the tile has road.
+ * @return True if and only if the tile has road.
*/
static bool IsRoadTile(TileIndex tile);
/**
* Checks whether the given tile is actually a tile with a road depot.
- * @param tile the tile to check.
+ * @param tile The tile to check.
* @pre AIMap::IsValidTile(tile).
- * @return true if and only if the tile has a road depot.
+ * @return True if and only if the tile has a road depot.
*/
static bool IsRoadDepotTile(TileIndex tile);
/**
* Checks whether the given tile is actually a tile with a road station.
- * @param tile the tile to check.
+ * @param tile The tile to check.
* @pre AIMap::IsValidTile(tile).
- * @return true if and only if the tile has a road station.
+ * @return True if and only if the tile has a road station.
*/
static bool IsRoadStationTile(TileIndex tile);
/**
* Checks whether the given tile is actually a tile with a drive through
- * road station.
- * @param tile the tile to check.
+ * road station.
+ * @param tile The tile to check.
* @pre AIMap::IsValidTile(tile).
- * @return true if and only if the tile has a drive through road station.
+ * @return True if and only if the tile has a drive through road station.
*/
static bool IsDriveThroughRoadStationTile(TileIndex tile);
/**
* Checks whether the given tiles are directly connected, i.e. whether
- * a road vehicle can travel from the center of the first tile to the
- * center of the second tile.
- * @param t1 the source tile.
- * @param t2 the destination tile.
- * @pre AIMap::IsValidTile(t1).
- * @pre AIMap::IsValidTile(t2).
- * @pre t1 and t2 are directly neighbouring tiles.
- * @return true if and only if a road vehicle can go from t1 to t2.
+ * a road vehicle can travel from the center of the first tile to the
+ * center of the second tile.
+ * @param tile_from The source tile.
+ * @param tile_to The destination tile.
+ * @pre AIMap::IsValidTile(tile_from).
+ * @pre AIMap::IsValidTile(tile_to).
+ * @pre 'tile_from' and 'tile_to' are directly neighbouring tiles.
+ * @return True if and only if a road vehicle can go from tile_from to tile_to.
*/
- static bool AreRoadTilesConnected(TileIndex t1, TileIndex t2);
+ static bool AreRoadTilesConnected(TileIndex tile_from, TileIndex tile_to);
/**
* Count how many neighbours are road.
- * @param tile the tile to check on.
+ * @param tile The tile to check on.
* @pre AIMap::IsValidTile(tile).
* @return 0 means no neighbour road; max value is 4.
*/
@@ -72,128 +72,126 @@
/**
* Gets the tile in front of a road depot.
- * @param depot the road depot tile.
+ * @param depot The road depot tile.
* @pre IsRoadDepotTile(depot).
- * @return the tile in front of the depot.
+ * @return The tile in front of the depot.
*/
static TileIndex GetRoadDepotFrontTile(TileIndex depot);
/**
* Gets the tile in front of a road station.
- * @param station the road station tile.
+ * @param station The road station tile.
* @pre IsRoadStationTile(station).
- * @return the tile in front of the road station.
+ * @return The tile in front of the road station.
*/
static TileIndex GetRoadStationFrontTile(TileIndex station);
/**
* Gets the tile at the back of a drive through road station.
- * So, one side of the drive through station is retrieved with
- * GetTileInFrontOfStation, the other with this function.
- * @param station the road station tile.
+ * So, one side of the drive through station is retrieved with
+ * GetTileInFrontOfStation, the other with this function.
+ * @param station The road station tile.
* @pre IsDriveThroughRoadStationTile(station).
- * @return the tile at the back of the drive through road station.
+ * @return The tile at the back of the drive through road station.
*/
static TileIndex GetDriveThroughBackTile(TileIndex station);
/**
- * Builds a road from the center of tile start to the
- * center of tile end.
- * @param start the start tile of the road.
- * @param end the end tile of the road.
- * @pre start is not equal to end
+ * Builds a road from the center of tile start to the center of tile end.
+ * @param start The start tile of the road.
+ * @param end The end tile of the road.
+ * @pre 'start' is not equal to 'end'.
* @pre AIMap::IsValidTile(start).
* @pre AIMap::IsValidTile(end).
- * @pre start and end are in a straight line, i.e.
+ * @pre 'start' and 'end' are in a straight line, i.e.
* AIMap::GetTileX(start) == AIMap::GetTileX(end) or
* AIMap::GetTileY(start) == AIMap::GetTileY(end).
- * @return whether the road has been/can be build or not.
+ * @return Whether the road has been/can be build or not.
*/
static bool BuildRoad(TileIndex start, TileIndex end);
/**
- * Builds a road from the edge of tile start to the
- * edge of tile end (both included).
- * @param start the start tile of the road.
- * @param end the end tile of the road.
- * @pre start is not equal to end
+ * Builds a road from the edge of tile start to the edge of tile end (both
+ * included).
+ * @param start The start tile of the road.
+ * @param end The end tile of the road.
+ * @pre 'start' is not equal to 'end'.
* @pre AIMap::IsValidTile(start).
* @pre AIMap::IsValidTile(end).
- * @pre start and end are in a straight line, i.e.
+ * @pre 'start' and 'end' are in a straight line, i.e.
* AIMap::GetTileX(start) == AIMap::GetTileX(end) or
* AIMap::GetTileY(start) == AIMap::GetTileY(end).
- * @return whether the road has been/can be build or not.
+ * @return Whether the road has been/can be build or not.
*/
static bool BuildRoadFull(TileIndex start, TileIndex end);
/**
* Builds a road depot.
- * @param tile place to build the depot.
- * @param front the tile exactly in front of the depot
+ * @param tile Place to build the depot.
+ * @param front The tile exactly in front of the depot.
* @pre AIMap::IsValidTile(tile).
* @pre AIMap::IsValidTile(front).
- * @pre tile is not equal to front
- * @return whether the road depot has been/can be build or not.
+ * @pre Tile is not equal to front.
+ * @return Whether the road depot has been/can be build or not.
*/
static bool BuildRoadDepot(TileIndex tile, TileIndex front);
/**
* Builds a road bus or truck station.
- * @param tile place to build the depot.
- * @param front the tile exactly in front of the station.
+ * @param tile Place to build the depot.
+ * @param front The tile exactly in front of the station.
* For drive-through stations either entrance side can be used.
- * @param truck whether to build a truck (true) or bus (false) station.
- * @param drive_through whether to make the station drive through or not.
+ * @param truck Whether to build a truck (true) or bus (false) station.
+ * @param drive_through Whether to make the station drive through or not.
* @pre AIMap::IsValidTile(tile).
* @pre AIMap::IsValidTile(front).
- * @pre tile is not equal to front
- * @return whether the station has been/can be build or not.
+ * @pre 'tile' is not equal to 'front'.
+ * @return Whether the station has been/can be build or not.
*/
static bool BuildRoadStation(TileIndex tile, TileIndex front, bool truck, bool drive_through);
/**
- * Removes a road from the center of tile start to the
- * center of tile end.
- * @param start the start tile of the road.
- * @param end the end tile of the road.
+ * Removes a road from the center of tile start to the center of tile end.
+ * @param start The start tile of the road.
+ * @param end The end tile of the road.
* @pre AIMap::IsValidTile(start).
* @pre AIMap::IsValidTile(end).
- * @pre start and end are in a straight line, i.e.
+ * @pre 'start' and 'end' are in a straight line, i.e.
* AIMap::GetTileX(start) == AIMap::GetTileX(end) or
* AIMap::GetTileY(start) == AIMap::GetTileY(end).
- * @return whether the road has been/can be removed or not.
+ * @return Whether the road has been/can be removed or not.
*/
static bool RemoveRoad(TileIndex start, TileIndex end);
/**
- * Removes a road from the edge of tile start to the
- * edge of tile end (both included).
- * @param start the start tile of the road.
- * @param end the end tile of the road.
+ * Removes a road from the edge of tile start to the edge of tile end (both
+ * included).
+ * @param start The start tile of the road.
+ * @param end The end tile of the road.
* @pre AIMap::IsValidTile(start).
* @pre AIMap::IsValidTile(end).
- * @pre start and end are in a straight line, i.e.
+ * @pre 'start' and 'end' are in a straight line, i.e.
* AIMap::GetTileX(start) == AIMap::GetTileX(end) or
* AIMap::GetTileY(start) == AIMap::GetTileY(end).
- * @return whether the road has been/can be removed or not.
+ * @return Whether the road has been/can be removed or not.
*/
static bool RemoveRoadFull(TileIndex start, TileIndex end);
/**
* Removes a road depot.
- * @param tile place to remove the depot from.
+ * @param tile Place to remove the depot from.
* @pre AIMap::IsValidTile(tile).
- * @pre tile is a road depot.
- * @return whether the road depot has been/can be removed or not.
+ * @pre Tile is a road depot.
+ * @return Whether the road depot has been/can be removed or not.
*/
static bool RemoveRoadDepot(TileIndex tile);
/**
* Removes a road bus or truck station.
- * @param tile place to remove the station from.
+ * @param tile Place to remove the station from.
* @pre AIMap::IsValidTile(tile).
- * @pre tile is a road station.
- * @return whether the station has been/can be removed or not.
+ * @pre Tile is a road station.
+ * @return Whether the station has been/can be removed or not.
*/
static bool RemoveRoadStation(TileIndex tile);
};
--- a/src/ai/api/ai_sign.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_sign.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -16,51 +16,48 @@
/**
* Gets the maximum sign index; there are no valid signs with a higher index.
- * @return the maximum sign index.
- * @post return value is always non-negative.
+ * @return The maximum sign index.
+ * @post Return value is always non-negative.
*/
static SignID GetMaxSignID();
/**
* Gets the number of signs. This is different than GetMaxSignID()
* because of the way OpenTTD works internally.
- * @return the number of signs.
- * @post return value is always non-negative.
+ * @return The number of signs.
+ * @post Return value is always non-negative.
*/
static int32 GetSignCount();
/**
* Checks whether the given sign index is valid.
- * @param sign_id the index to check.
- * @return true if and only if the sign is valid.
+ * @param sign_id The index to check.
+ * @return True if and only if the sign is valid.
*/
static bool IsValidSign(SignID sign_id);
/**
* Get the text on the sign.
- * @param sign_id the sign to get the text of.
- * @pre sign_id has to be valid (use IsValidSign()).
- * @return the text on the sign.
- * @note the returned name must be free'd (C++ only).
+ * @param sign_id The sign to get the text of.
+ * @pre IsValidSign(sign_id).
+ * @return The text on the sign.
*/
static char *GetText(SignID sign_id);
/**
* Gets the location of the sign.
- * @param sign_id the sign to get the location of.
- * @pre sign_id has to be valid (use IsValidSign()).
- * @return the location of the sign.
- * @post return value is always valid with AIMap::IsValidTile().
+ * @param sign_id The sign to get the location of.
+ * @pre IsValidSign(sign_id).
+ * @return The location of the sign.
*/
static TileIndex GetLocation(SignID sign_id);
/**
* Builds a sign on the map.
- * @param location the place to build the sign.
- * @param text the text to place on the sign.
+ * @param location The place to build the sign.
+ * @param text The text to place on the sign.
* @pre AIMap::IsValidTile(location).
- * @pre text is not NULL and non-empty, i.e. length is positive.
- * @return the SignID of the build sign (use IsValidSign() to check for validity).
+ * @return The SignID of the build sign (use IsValidSign() to check for validity).
* In test-mode it returns 0 if successful, or any other value to indicate
* failure.
*/
@@ -68,9 +65,9 @@
/**
* Removes a sign from the map.
- * @param sign_id the sign to remove.
- * @pre sign_id has to be valid (use IsValidSign()).
- * @return true if and only if the sign has been removed.
+ * @param sign_id The sign to remove.
+ * @pre IsValidSign(sign_id).
+ * @return True if and only if the sign has been removed.
*/
static bool RemoveSign(SignID sign_id);
};
--- a/src/ai/api/ai_station.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_station.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -19,69 +19,69 @@
* Type of stations known in the game.
*/
enum StationType {
- STATION_ANY = 0x00,
- STATION_TRAIN = 0x01,
- STATION_TRUCK_STOP = 0x02,
- STATION_BUS_STOP = 0x04,
- STATION_AIRPORT = 0x08,
- STATION_DOCK = 0x10,
+ STATION_ANY = 0x00, //!< All station types
+ STATION_TRAIN = 0x01, //!< Train station
+ STATION_TRUCK_STOP = 0x02, //!< Truck station
+ STATION_BUS_STOP = 0x04, //!< Bus station
+ STATION_AIRPORT = 0x08, //!< Airport
+ STATION_DOCK = 0x10, //!< Dock
};
/**
* Checks whether the given station is valid and owned by you.
- * @param station_id the station to check.
- * @return true if and only if the station is valid.
+ * @param station_id The station to check.
+ * @return True if and only if the station is valid.
*/
static bool IsValidStation(StationID station_id);
/**
- * Get the stationID of a tile, if there is a station.
- * @param tile the tile to find the stationID of
+ * Get the StationID of a tile, if there is a station.
+ * @param tile The tile to find the stationID of
* @return StationID of the station.
- * @post use IsValidStation to see if the station is valid.
+ * @post Use IsValidStation() to see if the station is valid.
*/
static StationID GetStationID(TileIndex tile);
/**
* Get the name of a station.
- * @param station_id the station to get the name of.
+ * @param station_id The station to get the name of.
* @pre IsValidStation(station_id).
- * @return the name of the station.
+ * @return The name of the station.
*/
static char *GetName(StationID station_id);
/**
* Get the current location of a station.
- * @param station_id the station to get the location of.
+ * @param station_id The station to get the location of.
* @pre IsValidStation(station_id).
- * @return the tile the station is currently on.
+ * @return The tile the station is currently on.
*/
static TileIndex GetLocation(StationID station_id);
/**
* See how much cargo there is waiting on a station.
- * @param station_id the station to get the cargo-waiting of.
- * @param cargo_id the cargo to get the cargo-waiting of.
+ * @param station_id The station to get the cargo-waiting of.
+ * @param cargo_id The cargo to get the cargo-waiting of.
* @pre IsValidStation(station_id).
* @pre IsValidCargo(cargo_id).
- * @return the amount of units waiting at the station.
+ * @return The amount of units waiting at the station.
*/
static int32 GetCargoWaiting(StationID station_id, CargoID cargo_id);
/**
* See how high the rating is of a cargo on a station.
- * @param station_id the station to get the cargo-rating of.
- * @param cargo_id the cargo to get the cargo-rating of.
+ * @param station_id The station to get the cargo-rating of.
+ * @param cargo_id The cargo to get the cargo-rating of.
* @pre IsValidStation(station_id).
* @pre IsValidCargo(cargo_id).
- * @return the rating in percent of the cargo on the station.
+ * @return The rating in percent of the cargo on the station.
*/
static int32 GetCargoRating(StationID station_id, CargoID cargo_id);
/**
* Get the coverage radius of this type of station.
- * @param type the type of station.
- * @return the radius in tiles.
+ * @param type The type of station.
+ * @return The radius in tiles.
*/
static int32 GetCoverageRadius(AIStation::StationType type);
@@ -103,6 +103,7 @@
*/
static int32 GetDistanceSquareToTile(StationID station_id, TileIndex tile);
};
+
DECLARE_ENUM_AS_BIT_SET(AIStation::StationType);
#endif /* AI_STATION_HPP */
--- a/src/ai/api/ai_tile.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_tile.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -17,66 +17,67 @@
/**
* Enumeration for the slope-type (from slopes.h).
*
- * This enumeration use the chars N,E,S,W corresponding the
- * direction north, east, south and west. The top corner of a tile
- * is the north-part of the tile. The whole slope is encoded with
- * 5 bits, 4 bits for each corner and 1 bit for a steep-flag.
+ * This enumeration use the chars N, E, S, W corresponding the
+ * direction North, East, South and West. The top corner of a tile
+ * is the north-part of the tile.
*/
enum Slope {
- SLOPE_FLAT = 0x00, ///< a flat tile
- SLOPE_W = 0x01, ///< the west corner of the tile is raised
- SLOPE_S = 0x02, ///< the south corner of the tile is raised
- SLOPE_E = 0x04, ///< the east corner of the tile is raised
- SLOPE_N = 0x08, ///< the north corner of the tile is raised
- SLOPE_STEEP = 0x10, ///< indicates the slope is steep
- SLOPE_NW = SLOPE_N | SLOPE_W, ///< north and west corner are raised
- SLOPE_SW = SLOPE_S | SLOPE_W, ///< south and west corner are raised
- SLOPE_SE = SLOPE_S | SLOPE_E, ///< south and east corner are raised
- SLOPE_NE = SLOPE_N | SLOPE_E, ///< north and east corner are raised
- SLOPE_EW = SLOPE_E | SLOPE_W, ///< east and west corner are raised
- SLOPE_NS = SLOPE_N | SLOPE_S, ///< north and south corner are raised
- SLOPE_ELEVATED = SLOPE_N | SLOPE_E | SLOPE_S | SLOPE_W, ///< all corner are raised, similar to SLOPE_FLAT
- SLOPE_NWS = SLOPE_N | SLOPE_W | SLOPE_S, ///< north, west and south corner are raised
- SLOPE_WSE = SLOPE_W | SLOPE_S | SLOPE_E, ///< west, south and east corner are raised
- SLOPE_SEN = SLOPE_S | SLOPE_E | SLOPE_N, ///< south, east and north corner are raised
- SLOPE_ENW = SLOPE_E | SLOPE_N | SLOPE_W, ///< east, north and west corner are raised
- SLOPE_STEEP_W = SLOPE_STEEP | SLOPE_NWS, ///< a steep slope falling to east (from west)
- SLOPE_STEEP_S = SLOPE_STEEP | SLOPE_WSE, ///< a steep slope falling to north (from south)
- SLOPE_STEEP_E = SLOPE_STEEP | SLOPE_SEN, ///< a steep slope falling to west (from east)
- SLOPE_STEEP_N = SLOPE_STEEP | SLOPE_ENW ///< a steep slope falling to south (from north)
+ SLOPE_FLAT = 0x00, //!< A flat tile
+ SLOPE_W = 0x01, //!< The west corner of the tile is raised
+ SLOPE_S = 0x02, //!< The south corner of the tile is raised
+ SLOPE_E = 0x04, //!< The east corner of the tile is raised
+ SLOPE_N = 0x08, //!< The north corner of the tile is raised
+ SLOPE_STEEP = 0x10, //!< Indicates the slope is steep
+ SLOPE_NW = SLOPE_N | SLOPE_W, //!< North and west corner are raised
+ SLOPE_SW = SLOPE_S | SLOPE_W, //!< South and west corner are raised
+ SLOPE_SE = SLOPE_S | SLOPE_E, //!< South and east corner are raised
+ SLOPE_NE = SLOPE_N | SLOPE_E, //!< North and east corner are raised
+ SLOPE_EW = SLOPE_E | SLOPE_W, //!< East and west corner are raised
+ SLOPE_NS = SLOPE_N | SLOPE_S, //!< North and south corner are raised
+ SLOPE_ELEVATED = SLOPE_N | SLOPE_E | SLOPE_S | SLOPE_W, //!< All corner are raised, similar to SLOPE_FLAT
+ SLOPE_NWS = SLOPE_N | SLOPE_W | SLOPE_S, //!< North, west and south corner are raised
+ SLOPE_WSE = SLOPE_W | SLOPE_S | SLOPE_E, //!< West, south and east corner are raised
+ SLOPE_SEN = SLOPE_S | SLOPE_E | SLOPE_N, //!< South, east and north corner are raised
+ SLOPE_ENW = SLOPE_E | SLOPE_N | SLOPE_W, //!< East, north and west corner are raised
+ SLOPE_STEEP_W = SLOPE_STEEP | SLOPE_NWS, //!< A steep slope falling to east (from west)
+ SLOPE_STEEP_S = SLOPE_STEEP | SLOPE_WSE, //!< A steep slope falling to north (from south)
+ SLOPE_STEEP_E = SLOPE_STEEP | SLOPE_SEN, //!< A steep slope falling to west (from east)
+ SLOPE_STEEP_N = SLOPE_STEEP | SLOPE_ENW //!< A steep slope falling to south (from north)
};
/**
- * Check if this tile is buildable (e.g.: no things on it that needs removing).
+ * Check if this tile is buildable, i.e. no things on it that needs
+ * demolishing.
+ * @param tile The tile to check on.
+ * @pre AIMap::IsValidTile(tile).
+ * @return True if it is buildable, false if not.
* @note Road and rail are considered buildable.
- * @param tile the tile to check on.
- * @pre AIMap::IsValidTile(tile).
- * @return true if it is buildable, false if not.
*/
static bool IsBuildable(TileIndex tile);
/**
- * Check if this tile is buildable in a rectangle around a tile, with the entry in the list as top-left.
+ * Check if this tile is buildable in a rectangle around a tile, with the
+ * entry in the list as top-left.
* @note Road and rail are considered buildable.
- * @param tile the tile to check on.
- * @param width the width of the rectangle.
- * @param height the height of the rectangle.
+ * @param tile The tile to check on.
+ * @param width The width of the rectangle.
+ * @param height The height of the rectangle.
* @pre AIMap::IsValidTile(tile).
- * @return true if it is buildable, false if not.
+ * @return True if it is buildable, false if not.
*/
static bool IsBuildableRectangle(TileIndex tile, uint width, uint height);
/**
* Check if a tile is water.
- * @param tile the tile to check on.
+ * @param tile The tile to check on.
* @pre AIMap::IsValidTile(tile).
- * @return true if it is water, false if not.
+ * @return True if it is water, false if not.
*/
static bool IsWater(TileIndex tile);
/**
* Get the slope of a tile.
- * @param tile the tile to check on.
+ * @param tile The tile to check on.
* @pre AIMap::IsValidTile(tile).
* @return 0 means flat, others indicate internal state of slope.
*/
@@ -84,9 +85,9 @@
/**
* Get the height of the tile.
- * @param tile the tile to check on.
+ * @param tile The tile to check on.
* @pre AIMap::IsValidTile(tile).
- * @return the height of the tile, ranging from 0 to 15.
+ * @return The height of the tile, ranging from 0 to 15.
*/
static int32 GetHeight(TileIndex tile);
@@ -94,13 +95,13 @@
* Check how much cargo this tile accepts.
* It creates a radius around the tile, and adds up all acceptance of this
* cargo.
- * @param tile the tile to check on.
- * @param cargo_type the cargo to check the acceptance of.
- * @param width the width of the station.
- * @param height the height of the station.
- * @param radius the radius of the station.
+ * @param tile The tile to check on.
+ * @param cargo_type The cargo to check the acceptance of.
+ * @param width The width of the station.
+ * @param height The height of the station.
+ * @param radius The radius of the station.
* @pre AIMap::IsValidTile(tile).
- * @return value below 8 means no acceptance; the more the better.
+ * @return Value below 8 means no acceptance; the more the better.
*/
static int32 GetCargoAcceptance(TileIndex tile, CargoID cargo_type, uint width, uint height, uint radius);
@@ -108,14 +109,14 @@
* Checks how many tiles in the radius produces this cargo.
* It creates a radius around the tile, and adds up all tiles that produce
* this cargo.
- * @param tile the tile to check on.
- * @param cargo_type the cargo to check the production of.
- * @param width the width of the station.
- * @param height the height of the station.
- * @param radius the radius of the station.
+ * @param tile The tile to check on.
+ * @param cargo_type The cargo to check the production of.
+ * @param width The width of the station.
+ * @param height The height of the station.
+ * @param radius The radius of the station.
* @pre AIMap::IsValidTile(tile).
- * @return the tiles that produce this cargo within radius of the tile.
- * @note town(houses) are not included in the value.
+ * @return The tiles that produce this cargo within radius of the tile.
+ * @note Town(houses) are not included in the value.
*/
static int32 GetCargoProduction(TileIndex tile, CargoID cargo_type, uint width, uint height, uint radius);
@@ -138,8 +139,8 @@
/**
* Raise the given corners of the tile. The corners can be combined,
* for example: SLOPE_N | SLOPE_W (= SLOPE_NW)
- * @param tile the tile to raise.
- * @param slope corners to raise (SLOPE_xxx).
+ * @param tile The tile to raise.
+ * @param slope Corners to raise (SLOPE_xxx).
* @pre AIMap::IsValidTile(tile).
* @return 0 means failed, 1 means success.
*/
@@ -148,8 +149,8 @@
/**
* Lower the given corners of the tile. The corners can be combined,
* for example: SLOPE_N | SLOPE_W (= SLOPE_NW)
- * @param tile the tile to lower.
- * @param slope corners to lower (SLOPE_xxx).
+ * @param tile The tile to lower.
+ * @param slope Corners to lower (SLOPE_xxx).
* @pre AIMap::IsValidTile(tile).
* @return 0 means failed, 1 means success.
*/
@@ -157,9 +158,9 @@
/**
* Destroy everything on the given tile.
- * @param tile the tile to demolish.
+ * @param tile The tile to demolish.
* @pre AIMap::IsValidTile(tile).
- * @return true if and only if the tile was demolished.
+ * @return True if and only if the tile was demolished.
*/
static bool DemolishTile(TileIndex tile);
};
--- a/src/ai/api/ai_town.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_town.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -17,50 +17,48 @@
/**
* Gets the maximum town index; there are no valid towns with a higher index.
- * @return the maximum town index.
- * @post return value is always non-negative.
+ * @return The maximum town index.
+ * @post Return value is always non-negative.
*/
static TownID GetMaxTownID();
/**
* Gets the number of towns. This is different than GetMaxTownID()
* because of the way OpenTTD works internally.
- * @return the number of towns.
- * @post return value is always non-negative.
+ * @return The number of towns.
+ * @post Return value is always non-negative.
*/
static int32 GetTownCount();
/**
* Checks whether the given town index is valid.
- * @param town_id the index to check.
- * @return true if and only if the town is valid.
+ * @param town_id The index to check.
+ * @return True if and only if the town is valid.
*/
static bool IsValidTown(TownID town_id);
/**
* Get the name of the town.
- * @param town_id the town to get the name of.
- * @pre town_id has to be valid (use IsValidTown()).
- * @return the name of the town.
- * @note the returned name must be free'd (C++ only).
+ * @param town_id The town to get the name of.
+ * @pre IsValidTown(town_id).
+ * @return The name of the town.
*/
static char *GetName(TownID town_id);
/**
* Gets the number of inhabitants in the town.
- * @param town_id the town to get the name of.
- * @pre town_id has to be valid (use IsValidTown()).
- * @return the number of inhabitants.
- * @post return value is always non-negative.
+ * @param town_id The town to get the name of.
+ * @pre IsValidTown(town_id).
+ * @return The number of inhabitants.
+ * @post Return value is always non-negative.
*/
static int32 GetPopulation(TownID town_id);
/**
* Gets the location of the town.
- * @param town_id the location of the town.
- * @pre town_id has to be valid (use IsValidTown()).
- * @return the location of the town.
- * @post return value is always valid with AIMap::IsValidTile().
+ * @param town_id The location of the town.
+ * @pre IsValidTown(town_id).
+ * @return The location of the town.
*/
static TileIndex GetLocation(TownID town_id);
@@ -69,6 +67,7 @@
* of the town.
* @param town_id The town to get the distance to.
* @param tile The tile to get the distance to.
+ * @pre IsValidTown(town_id).
* @return The distance between town and tile.
*/
static int32 GetDistanceManhattanToTile(TownID town_id, TileIndex tile);
@@ -78,6 +77,7 @@
* of the town.
* @param town_id The town to get the distance to.
* @param tile The tile to get the distance to.
+ * @pre IsValidTown(town_id).
* @return The distance between town and tile.
*/
static int32 GetDistanceSquareToTile(TownID town_id, TileIndex tile);
--- a/src/ai/api/ai_tunnel.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_tunnel.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -17,17 +17,19 @@
/**
* Check whether the tile is an entrance to a tunnel.
+ * @param tile The tile to check.
* @pre AIMap::IsValidTile(tile).
- * @param tile The tile to check.
- * @note true if and only if the tile is the beginning or end of a tunnel.
+ * @return True if and only if the tile is the beginning or end of a tunnel.
*/
static bool IsTunnelTile(TileIndex tile);
/**
- * Get the tile that exits on the other end of a (would be) tunnel starting at tile.
+ * Get the tile that exits on the other end of a (would be) tunnel starting
+ * at tile.
+ * @param tile The tile that is an entrance to a tunnel or the tile where you may want to build a tunnel.
* @pre AIMap::IsValidTile(tile).
- * @param tile A tile that is an entrance to a tunnel or a tile where you may want to build a tunnel.
- * @return The TileIndex that is the other end of the (would be) tunnel, or 'tile' if no other end was found (crossing tunnels).
+ * @return The TileIndex that is the other end of the (would be) tunnel, or
+ * 'tile' if no other end was found (crossing tunnels).
*/
static TileIndex GetOtherTunnelEnd(TileIndex tile);
@@ -38,7 +40,7 @@
* @param start Where to start the tunnel.
* @param vehicle_type The vehicle-type of tunnel to build.
* @pre AIMap::IsValidTile(start).
- * @pre vehicle_type is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
+ * @pre 'vehicle_type' is either AIVehicle::VEHICLE_RAIL or AIVEHICLE::VEHICLE_ROAD.
* @return Whether the tunnel has been/can be build or not.
* @note The slope of a tile can be determined by AITile::GetSlope(TileIndex).
*/
@@ -46,7 +48,7 @@
/**
* Remove the tunnel whose entrance is located at tile.
- * @param tile a tile that is an entrance to a tunnel.
+ * @param tile The tile that is an entrance to a tunnel.
* @pre AIMap::IsValidTile(tile) && IsTunnelTile(tile).
* @return Whether the tunnel has been/can be removed or not.
*/
--- a/src/ai/api/ai_vehicle.hpp Mon Mar 31 07:50:27 2008 +0000
+++ b/src/ai/api/ai_vehicle.hpp Mon Mar 31 08:42:20 2008 +0000
@@ -21,152 +21,152 @@
*/
enum VehicleType {
/* Order IS important, as it now matches the internal state of the game for vehicle type */
- VEHICLE_RAIL,
- VEHICLE_ROAD,
- VEHICLE_WATER,
- VEHICLE_AIR,
- VEHICLE_INVALID = 0xFF,
+ VEHICLE_RAIL, //!< Rail type vehicle.
+ VEHICLE_ROAD, //!< Road type vehicle (bus / truck).
+ VEHICLE_WATER, //!< Water type vehicle.
+ VEHICLE_AIR, //!< Air type vehicle.
+ VEHICLE_INVALID = 0xFF, //!< Invalid vehicle type.
};
/**
* Checks whether the given vehicle is valid and owned by you.
- * @param vehicle_id the vehicle to check.
- * @return true if and only if the vehicle is valid.
+ * @param vehicle_id The vehicle to check.
+ * @return True if and only if the vehicle is valid.
*/
static bool IsValidVehicle(VehicleID vehicle_id);
/**
* Set the name of a vehicle.
- * @param vehicle_id the vehicle to set the name for.
- * @param name the name for the vehicle.
+ * @param vehicle_id The vehicle to set the name for.
+ * @param name The name for the vehicle.
* @pre IsValidVehicle(vehicle_id).
* @pre Name has to be unique.
* @pre You have to own the vehicle.
- * @return true if and only if the name was changed.
+ * @return True if and only if the name was changed.
*/
static bool SetName(VehicleID vehicle_id, const char *name);
/**
* Get the name of a vehicle.
- * @param vehicle_id the vehicle to get the name of.
+ * @param vehicle_id The vehicle to get the name of.
* @pre IsValidVehicle(vehicle_id).
- * @return the name the vehicle has.
+ * @return The name the vehicle has.
*/
static char *GetName(VehicleID vehicle_id);
/**
* Get the current location of a vehicle.
- * @param vehicle_id the vehicle to get the location of.
+ * @param vehicle_id The vehicle to get the location of.
* @pre IsValidVehicle(vehicle_id).
- * @return the tile the vehicle is currently on.
+ * @return The tile the vehicle is currently on.
*/
static TileIndex GetLocation(VehicleID vehicle_id);
/**
* Get the engine-type of a vehicle.
- * @param vehicle_id the vehicle to get the engine-type of.
+ * @param vehicle_id The vehicle to get the engine-type of.
* @pre IsValidVehicle(vehicle_id).
- * @return the engine type the vehicle has.
+ * @return The engine type the vehicle has.
*/
static EngineID GetEngineType(VehicleID vehicle_id);
/**
* Get the unitnumber of a vehicle.
- * @param vehicle_id the vehicle to get the unitnumber of.
+ * @param vehicle_id The vehicle to get the unitnumber of.
* @pre IsValidVehicle(vehicle_id).
- * @return the unitnumber the vehicle has.
+ * @return The unitnumber the vehicle has.
*/
static int32 GetUnitNumber(VehicleID vehicle_id);
/**
* Get the current age of a vehicle.
- * @note age is in days.
- * @param vehicle_id the vehicle to get the age of.
+ * @param vehicle_id The vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
- * @return the current age the vehicle has.
+ * @return The current age the vehicle has.
+ * @note The age is in days.
*/
static int32 GetAge(VehicleID vehicle_id);
/**
- * Get the max age of a vehicle.
- * @note age is in days.
- * @param vehicle_id the vehicle to get the age of.
+ * Get the maximum age of a vehicle.
+ * @param vehicle_id The vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
- * @return the max age the vehicle has.
+ * @return The maximum age the vehicle has.
+ * @note The age is in days.
*/
static int32 GetMaxAge(VehicleID vehicle_id);
/**
- * Get the age a vehicle has left (max - current).
- * @note age is in days.
- * @param vehicle_id the vehicle to get the age of.
+ * Get the age a vehicle has left (maximum - current).
+ * @param vehicle_id The vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
- * @return the age the vehicle has left.
+ * @return The age the vehicle has left.
+ * @note The age is in days.
*/
static int32 GetAgeLeft(VehicleID vehicle_id);
/**
* Get the running cost of this vehicle.
- * @note cost is per year; divide by 364 to get per day.
- * @note this is not equal to AIEngine::GetRunningCost for Trains, because
- * wagons and second engines can add up in the calculation too.
- * @param vehicle_id the vehicle to get the age of.
+ * @param vehicle_id The vehicle to get the age of.
* @pre IsValidVehicle(vehicle_id).
* @return The running cost of the vehicle per year.
+ * @note Cost is per year; divide by 364 to get per day.
+ * @note This is not equal to AIEngine::GetRunningCost for Trains, because
+ * wagons and second engines can add up in the calculation too.
*/
static Money GetRunningCost(VehicleID vehicle_id);
/**
* Get the current profit of a vehicle.
- * @param vehicle_id the vehicle to get the profit of.
+ * @param vehicle_id The vehicle to get the profit of.
* @pre IsValidVehicle(vehicle_id).
- * @return the current profit the vehicle has.
+ * @return The current profit the vehicle has.
*/
static int32 GetProfitThisYear(VehicleID vehicle_id);
/**
* Get the profit of last year of a vehicle.
- * @param vehicle_id the vehicle to get the profit of.
+ * @param vehicle_id The vehicle to get the profit of.
* @pre IsValidVehicle(vehicle_id).
- * @return the profit the vehicle had last year.
+ * @return The profit the vehicle had last year.
*/
static int32 GetProfitLastYear(VehicleID vehicle_id);
/**
* Get the type of vehicle.
- * @param vehicle_id the vehicle to get the type of.
+ * @param vehicle_id The vehicle to get the type of.
* @pre IsValidVehicle(vehicle_id).
- * @return the vehicle type.
+ * @return The vehicle type.
*/
static AIVehicle::VehicleType GetVehicleType(VehicleID vehicle_id);
/**
* Check if a vehicle is in a depot.
- * @param vehicle_id the vehicle to check.
- * @pre isValidVehicle(vehicle_id).
- * @return true if and only if the vehicle is in a depot.
+ * @param vehicle_id The vehicle to check.
+ * @pre IsValidVehicle(vehicle_id).
+ * @return True if and only if the vehicle is in a depot.
*/
static bool IsInDepot(VehicleID vehicle_id);
/**
* Check if a vehicle is in a depot and stopped.
- * @param vehicle_id the vehicle to check.
- * @pre isValidVehicle(vehicle_id).
- * @return true if and only if the vehicle is in a depot and stopped.
+ * @param vehicle_id The vehicle to check.
+ * @pre IsValidVehicle(vehicle_id).
+ * @return True if and only if the vehicle is in a depot and stopped.
*/
static bool IsStoppedInDepot(VehicleID vehicle_id);
/**
* Builds a vehicle with the given engine at the given depot.
- * @param depot the depot where the vehicle will be build.
- * @param engine_id the engine to use for this vehicle.
- * @pre the tile at depot has a depot that can build the engine and
+ * @param depot The depot where the vehicle will be build.
+ * @param engine_id The engine to use for this vehicle.
+ * @pre The tile at depot has a depot that can build the engine and
* is owned by you.
* @pre IsValidEngine(engine_id).
- * @return the VehicleID of the new vehicle, or an invalid VehicleID when
+ * @return The VehicleID of the new vehicle, or an invalid VehicleID when
* it failed. Check the return value using IsValidVehicle. In test-mode
* 0 is returned if it was successful; any other value indicates failure.
- * @note in test-mode it means you can't assign orders yet to this vehicle,
+ * @note In Test Mode it means you can't assign orders yet to this vehicle,
* as the vehicle isn't really built yet. Build it for real first before
* assigning orders.
*/
@@ -174,12 +174,12 @@
/**
* Clones a vehicle at the given depot, copying or cloning it's orders.
- * @param depot the depot where the vehicle will be build.
- * @param vehicle_id the vehicle to use as example for the new vehicle.
- * @param share_orders should the orders be copied or shared?
- * @pre the tile at depot has a depot.
+ * @param depot The depot where the vehicle will be build.
+ * @param vehicle_id The vehicle to use as example for the new vehicle.
+ * @param share_orders Should the orders be copied or shared?
+ * @pre The tile 'depot' has a depot on it, allowing 'vehicle_id'-type vehicles.
* @pre IsValidVehicle(vehicle_id).
- * @return the VehicleID of the new vehicle, or an invalid VehicleID when
+ * @return The VehicleID of the new vehicle, or an invalid VehicleID when
* it failed. Check the return value using IsValidVehicle. In test-mode
* 0 is returned if it was successful; any other value indicates failure.
*/
@@ -187,48 +187,48 @@
/**
* Refits a vehicle to the given cargo type
- * @param vehicle_id the vehicle to refit
- * @param cargo the cargo to refit to
+ * @param vehicle_id The vehicle to refit
+ * @param cargo The cargo to refit to.
* @pre IsValidVehicle(vehicle_id).
- * @pre AICargo::IsValidCargo(cargo)
- * @pre you must own the vehicle
- * @pre the vehicle must be stopped in the depot
- * @return true if and only if the refit succeeded.
+ * @pre AICargo::IsValidCargo(cargo).
+ * @pre You must own the vehicle.
+ * @pre The vehicle must be stopped in the depot.
+ * @return True if and only if the refit succeeded.
*/
static bool RefitVehicle(VehicleID vehicle_id, CargoID cargo);
/**
* Sells the given vehicle.
- * @param vehicle_id the vehicle to sell.
+ * @param vehicle_id The vehicle to sell.
* @pre IsValidVehicle(vehicle_id).
- * @pre you must own the vehicle
- * @pre the vehicle must be stopped in the depot
- * @return true if and only if the vehicle has been sold.
+ * @pre You must own the vehicle.
+ * @pre The vehicle must be stopped in the depot.
+ * @return True if and only if the vehicle has been sold.
*/
static bool SellVehicle(VehicleID vehicle_id);
/**
* Sends the given vehicle to a depot.
- * @param vehicle_id the vehicle to send to a depot.
+ * @param vehicle_id The vehicle to send to a depot.
* @pre IsValidVehicle(vehicle_id).
- * @return true if and only if the vehicle has been sent to a depot.
+ * @return True if and only if the vehicle has been sent to a depot.
*/
static bool SendVehicleToDepot(VehicleID vehicle_id);
/**
* Starts or stops the given vehicle depending on the current state.
- * @param vehicle_id the vehicle to start/stop.
+ * @param vehicle_id The vehicle to start/stop.
* @pre IsValidVehicle(vehicle_id).
- * @return true if and only if the vehicle has been started or stopped.
+ * @return True if and only if the vehicle has been started or stopped.
*/
static bool StartStopVehicle(VehicleID vehicle_id);
/**
* Skips the current order of the given vehicle.
- * @param vehicle_id the vehicle to skip the order for.
- * @param order_id the selected order to which we want to skip.
+ * @param vehicle_id The vehicle to skip the order for.
+ * @param order_id The selected order to which we want to skip.
* @pre IsValidVehicleOrder(vehicle_id, order_id).
- * @return true if and only if the order has been skipped.
+ * @return True if and only if the order has been skipped.
*/
static bool SkipToVehicleOrder(VehicleID vehicle_id, uint32 order_id);
};