# HG changeset patch # User truebrain # Date 1206952940 0 # Node ID 0839682a601baac09c1228ba3fd1560d59c38563 # Parent c9ec4f82e0d091d0e2e979893748f585239027a2 (svn r12504) [NoAI] -Documentation: the last few files which now are consistent in their comments (anyway, so I hope :)) diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_bridge.hpp --- 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); diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_order.hpp --- 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); }; diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_road.hpp --- 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); }; diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_sign.hpp --- 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); }; diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_station.hpp --- 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 */ diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_tile.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); }; diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_town.hpp --- 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); diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_tunnel.hpp --- 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. */ diff -r c9ec4f82e0d0 -r 0839682a601b src/ai/api/ai_vehicle.hpp --- 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); };