# HG changeset patch # User truebrain # Date 1206949071 0 # Node ID 54afebfded499ae324ff4f41b804ec3ec963ea8b # Parent 2541c2d325edb812df6349ac4ed9db10541086ca (svn r12502) [NoAI] -Documentation: even more comment consistancy diff -r 2541c2d325ed -r 54afebfded49 src/ai/api/ai_engine.hpp --- a/src/ai/api/ai_engine.hpp Mon Mar 31 07:21:39 2008 +0000 +++ b/src/ai/api/ai_engine.hpp Mon Mar 31 07:37:51 2008 +0000 @@ -17,33 +17,33 @@ /** * Checks whether the given engine type is valid and buildable by you. - * @param engine_id the engine to check. - * @return true if and only if the engine type is valid. + * @param engine_id The engine to check. + * @return True if and only if the engine type is valid. */ static bool IsValidEngine(EngineID engine_id); /** * Get the name of an engine. - * @param engine_id the engine to get the name of. + * @param engine_id The engine to get the name of. * @pre IsValidEngine(engine_id). - * @return the name the engine has. + * @return The name the engine has. */ static char *GetName(EngineID engine_id); /** * Get the cargo-type of an engine. In case it can transport 2 cargos, it * returns the first. - * @param engine_id the engine to get the cargo-type of. + * @param engine_id The engine to get the cargo-type of. * @pre IsValidEngine(engine_id). - * @return the cargo-type of the engine. + * @return The cargo-type of the engine. */ static CargoID GetCargoType(EngineID engine_id); /** * Check if the cargo of an engine can be refitted to your requested. If * the engine already allows this cargo, the function also returns true. - * @param engine_id the engine to check for refitting. - * @param cargo_id the cargo to check for refitting. + * @param engine_id The engine to check for refitting. + * @param cargo_id The cargo to check for refitting. * @pre IsValidEngine(engine_id). * @pre AICargo::IsValidCargo(cargo_id). * @return True if the engine can carry this cargo, either via refit, or @@ -54,9 +54,9 @@ /** * Get the capacity of an engine. In case it can transport 2 cargos, it * returns the first. - * @param engine_id the engine to get the capacity of. + * @param engine_id The engine to get the capacity of. * @pre IsValidEngine(engine_id). - * @return the capacity of the engine. + * @return The capacity of the engine. */ static uint32 GetCapacity(EngineID engine_id); @@ -64,41 +64,41 @@ * Get the reliability of an engine. The value is between 0 and 100, where * 100 means 100% reliability (never breaks down) and 0 means 0% * reliability (you most likely don't want to buy it). - * @param engine_id the engine to get the reliability of. + * @param engine_id The engine to get the reliability of. * @pre IsValidEngine(engine_id). - * @return the reliability the engine has. + * @return The reliability the engine has. */ static uint32 GetReliability(EngineID engine_id); /** - * Get the max speed of an engine (in km/h). - * @param engine_id the engine to get the max speed of. + * Get the maximum speed of an engine (in km/h). + * @param engine_id The engine to get the maximum speed of. * @pre IsValidEngine(engine_id). - * @return the max speed the engine has. + * @return The maximum speed the engine has. */ static uint32 GetMaxSpeed(EngineID engine_id); /** * Get the new cost of an engine. - * @param engine_id the engine to get the new cost of. + * @param engine_id The engine to get the new cost of. * @pre IsValidEngine(engine_id). - * @return the new cost the engine has. + * @return The new cost the engine has. */ static uint32 GetPrice(EngineID engine_id); /** - * Get the max age of a brand new engine. + * Get the maximum age of a brand new engine. * @note age is in days; divide by 366 to get per year. - * @param engine_id the engine to get the max age of. + * @param engine_id The engine to get the maximum age of. * @pre IsValidEngine(engine_id). - * @returns The max age of a new engine in days. + * @returns The maximum age of a new engine in days. */ static uint32 GetMaxAge(EngineID engine_id); /** * Get the running cost of an engine. * @note cost is per year; divide by 364 to get per day. - * @param engine_id the engine to get the running cost of. + * @param engine_id The engine to get the running cost of. * @pre IsValidEngine(engine_id). * @return The running cost of a vehicle per year. */ @@ -106,9 +106,9 @@ /** * Get the type of an engine. - * @param engine_id the engine to get the type of. + * @param engine_id The engine to get the type of. * @pre IsValidEngine(engine_id). - * @return the type the engine has. + * @return The type the engine has. */ static AIVehicle::VehicleType GetVehicleType(EngineID engine_id); }; diff -r 2541c2d325ed -r 54afebfded49 src/ai/api/ai_industry.hpp --- a/src/ai/api/ai_industry.hpp Mon Mar 31 07:21:39 2008 +0000 +++ b/src/ai/api/ai_industry.hpp Mon Mar 31 07:37:51 2008 +0000 @@ -18,91 +18,90 @@ /** * Gets the maximum industry index; there are no valid industries with a * higher index. - * @return the maximum industry index. - * @post return value is always non-negative. + * @return The maximum industry index. + * @post Return value is always non-negative. */ static IndustryID GetMaxIndustryID(); /** * Gets the number of industries. This is different than GetMaxIndustryID() * because of the way OpenTTD works internally. - * @return the number of industries. - * @post return value is always non-negative. + * @return The number of industries. + * @post Return value is always non-negative. */ static int32 GetIndustryCount(); /** * Checks whether the given industry index is valid. - * @param industry_id the index to check. - * @return true if and only if the industry is valid. + * @param industry_id The index to check. + * @return True if and only if the industry is valid. */ static bool IsValidIndustry(IndustryID industry_id); /** * Get the name of the industry. - * @param industry_id the industry to get the name of. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @return the name of the industry. - * @note the returned name must be free'd (C++ only). + * @param industry_id The industry to get the name of. + * @pre IsValidIndustry(industry_id). + * @return The name of the industry. */ static char *GetName(IndustryID industry_id); /** * Gets the production of a cargo of the industry. - * @param industry_id the index of the industry. - * @param cargo_id the index of the cargo. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @pre cargo_id has to be valid (use IsValidCargo()). - * @return the production of the cargo for this industry, or -1 if + * @param industry_id The index of the industry. + * @param cargo_id The index of the cargo. + * @pre IsValidIndustry(industry_id). + * @pre AICargo::IsValidCargo(cargo_id). + * @return The production of the cargo for this industry, or -1 if * this industry doesn't produce this cargo. */ static int32 GetProduction(IndustryID industry_id, CargoID cargo_id); /** * See if an industry accepts a certain cargo. - * @param industry_id the index of the industry. - * @param cargo_id the index of the cargo. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @pre cargo_id has to be valid (use IsValidCargo()). - * @return the production of the cargo for this industry. + * @param industry_id The index of the industry. + * @param cargo_id The index of the cargo. + * @pre IsValidIndustry(industry_id). + * @pre AICargo::IsValidCargo(cargo_id). + * @return The production of the cargo for this industry. */ static bool IsCargoAccepted(IndustryID industry_id, CargoID cargo_id); /** - * Gets the location of the industry. - * @param industry_id the index of the industry. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @return the location of the industry. - * @post return value is always valid with AIMap::IsValidTile(). - */ - static TileIndex GetLocation(IndustryID industry_id); - - - /** * Get the total last month's production of the given cargo at an industry. - * @param industry_id the index of the industry. - * @param cargo_id the index of the cargo. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @pre cargo_id has to be valid (use IsValidCargo()). - * @return the last month's production of the given cargo for this industry. + * @param industry_id The index of the industry. + * @param cargo_id The index of the cargo. + * @pre IsValidIndustry(industry_id). + * @pre AICargo::IsValidCargo(cargo_id). + * @return The last month's production of the given cargo for this industry. */ static uint16 GetLastMonthProduction(IndustryID industry_id, CargoID cargo_id); /** * Get the total amount of cargo transported from an industry last month. - * @param industry_id the index of the industry. - * @param cargo_id the index of the cargo. - * @pre industry_id has to be valid (use IsValidIndustry()). - * @pre cargo_id has to be valid (use IsValidCargo()). - * @return the amount of given cargo transported from this industry last month. + * @param industry_id The index of the industry. + * @param cargo_id The index of the cargo. + * @pre IsValidIndustry(industry_id). + * @pre AICargo::IsValidCargo(cargo_id). + * @return The amount of given cargo transported from this industry last month. */ static uint16 GetLastMonthTransported(IndustryID industry_id, CargoID cargo_id); /** + * Gets the location of the industry. + * @param industry_id The index of the industry. + * @pre IsValidIndustry(industry_id). + * @return The location of the industry. + */ + static TileIndex GetLocation(IndustryID industry_id); + + /** * Get the manhattan distance from the tile to the AIIndustry::GetLocation() * of the industry. * @param industry_id The industry to get the distance to. * @param tile The tile to get the distance to. + * @pre IsValidIndustry(industry_id). + * @pre AIMap::IsValidTile(tile). * @return The distance between industry and tile. */ static int32 GetDistanceManhattanToTile(IndustryID industry_id, TileIndex tile); @@ -112,6 +111,8 @@ * of the industry. * @param industry_id The industry to get the distance to. * @param tile The tile to get the distance to. + * @pre IsValidIndustry(industry_id). + * @pre AIMap::IsValidTile(tile). * @return The distance between industry and tile. */ static int32 GetDistanceSquareToTile(IndustryID industry_id, TileIndex tile); diff -r 2541c2d325ed -r 54afebfded49 src/ai/api/ai_map.hpp --- a/src/ai/api/ai_map.hpp Mon Mar 31 07:21:39 2008 +0000 +++ b/src/ai/api/ai_map.hpp Mon Mar 31 07:37:51 2008 +0000 @@ -16,102 +16,102 @@ /** * Checks whether the given tile is valid. - * @param t the tile to check. - * @return true is the tile it within the boundaries of the map. + * @param tile The tile to check. + * @return True is the tile it within the boundaries of the map. */ - static bool IsValidTile(TileIndex t); + static bool IsValidTile(TileIndex tile); /** * Gets the number of tiles in the map. - * @return the size of the map in tiles. - * @post return value is always positive. + * @return The size of the map in tiles. + * @post Return value is always positive. */ static TileIndex GetMapSize(); /** * Gets the amount of tiles along the SW and NE border. - * @return the length along the SW and NE borders. - * @post return value is always positive. + * @return The length along the SW and NE borders. + * @post Return value is always positive. */ static uint32 GetMapSizeX(); /** * Gets the amount of tiles along the SE and NW border. - * @return the length along the SE and NW borders. - * @post return value is always positive. + * @return The length along the SE and NW borders. + * @post Return value is always positive. */ static uint32 GetMapSizeY(); /** * Gets the place along the SW/NE border (X-value). - * @param t the tile to get the X-value of. - * @pre t has to be valid (use IsValidTile(t)). - * @return the X-value. - * @post return value is lower than GetMapSizeX(). + * @param tile The tile to get the X-value of. + * @pre IsValidTile(tile). + * @return The X-value. + * @post Return value is always lower than GetMapSizeX(). */ - static uint32 GetTileX(TileIndex t); + static uint32 GetTileX(TileIndex tile); /** * Gets the place along the SE/NW border (Y-value). - * @param t the tile to get the Y-value of. - * @pre t has to be valid (use IsValidTile(t)). - * @return the Y-value. - * @post return value is lower than GetMapSizeY(). + * @param tile The tile to get the Y-value of. + * @pre IsValidTile(tile). + * @return The Y-value. + * @post Return value is always lower than GetMapSizeY(). */ - static uint32 GetTileY(TileIndex t); + static uint32 GetTileY(TileIndex tile); /** * Gets the TileIndex given a x,y-coordinate. - * @param x the X coordinate. - * @param y the Y coordinate. - * @pre x has to be lower than GetMapSizeX(). - * @pre y has to be lower than GetMapSizeY(). - * @return the TileIndex for the given x,y coordinate. + * @param x The X coordinate. + * @param y The Y coordinate. + * @pre x < GetMapSizeX(). + * @pre y < GetMapSizeY(). + * @return The TileIndex for the given (x,y) coordinate. */ static TileIndex GetTileIndex(uint32 x, uint32 y); /** * Calculates the Manhattan distance; the difference of - * the X and Y added together. - * @param t1 the start. - * @param t2 the destination. - * @pre t1 has to be valid (use IsValidTile(t1)). - * @pre t2 has to be valid (use IsValidTile(t2)). - * @return the Manhattan distance. + * the X and Y added together. + * @param tile_from The start tile. + * @param tile_to The destination tile. + * @pre IsValidTile(tile_from). + * @pre IsValidTile(tile_to). + * @return The Manhattan distance between the tiles. */ - static uint32 DistanceManhattan(TileIndex t1, TileIndex t2); + static uint32 DistanceManhattan(TileIndex tile_from, TileIndex tile_to); /** - * Calculates the distance between xy1 and xy2 via 1D calculation. - * (so the distance between X or the distance between Y, depending - * on which one is bigger). - * @param t1 the start. - * @param t2 the destination. - * @pre t1 has to be valid (use IsValidTile(t1)). - * @pre t2 has to be valid (use IsValidTile(t2)). - * @return the maximum distance of X and Y. + * Calculates the distance between two tiles via 1D calculation. + * This means the distance between X or the distance between Y, depending + * on which one is bigger. + * @param tile_from The start tile. + * @param tile_to The destination tile. + * @pre IsValidTile(tile_from). + * @pre IsValidTile(tile_to). + * @return The maximum distance between the tiles. */ - static uint32 DistanceMax(TileIndex t1, TileIndex t2); + static uint32 DistanceMax(TileIndex tile_from, TileIndex tile_to); /** * The squared distance between the two tiles. - * This is the distance is the length of the shortest straight - * line between both points. - * @param t1 the start. - * @param t2 the destination. - * @pre t1 has to be valid (use IsValidTile(t1)). - * @pre t2 has to be valid (use IsValidTile(t2)). - * @return the distance. + * This is the distance is the length of the shortest straight line + * between both points. + * @param tile_from The start tile. + * @param tile_to The destination tile. + * @pre IsValidTile(tile_from). + * @pre IsValidTile(tile_to). + * @return The squared distance between the tiles. */ - static uint32 DistanceSquare(TileIndex t1, TileIndex t2); + static uint32 DistanceSquare(TileIndex tile_from, TileIndex tile_to); /** * Calculates the shortest distance to the edge. - * @param t from where the distance has to be calculated. - * @pre t has to be valid (use IsValidTile(t)). - * @return the distances to the closest edge. + * @param tile From where the distance has to be calculated. + * @pre IsValidTile(tile). + * @return The distances to the closest edge. */ - static uint32 DistanceFromEdge(TileIndex t); + static uint32 DistanceFromEdge(TileIndex tile); }; #endif /* AI_MAP_HPP */ diff -r 2541c2d325ed -r 54afebfded49 src/ai/api/ai_marine.hpp --- a/src/ai/api/ai_marine.hpp Mon Mar 31 07:21:39 2008 +0000 +++ b/src/ai/api/ai_marine.hpp Mon Mar 31 07:37:51 2008 +0000 @@ -16,122 +16,122 @@ /** * Checks whether the given tile is actually a tile with a water 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 water depot. + * @return True if and only if the tile has a water depot. */ static bool IsWaterDepotTile(TileIndex tile); /** * Checks whether the given tile is actually a tile with a dock. - * @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 dock. + * @return True if and only if the tile has a dock. */ static bool IsDockTile(TileIndex tile); /** * Checks whether the given tile is actually a tile with a buoy. - * @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 buoy. + * @return True if and only if the tile has a buoy. */ static bool IsBuoyTile(TileIndex tile); /** * Checks whether the given tile is actually a tile with a lock. - * @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 lock. + * @return True if and only if the tile has a lock. */ static bool IsLockTile(TileIndex tile); /** * Checks whether the given tile is actually a tile with a canal. - * @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 canal. + * @return True if and only if the tile has a canal. */ static bool IsCanalTile(TileIndex tile); /** * Builds a water depot on tile. - * @param tile the tile where the water depot will be build. - * @param vertical if true, depot will be vertical, else horizontal. + * @param tile The tile where the water depot will be build. + * @param vertical If true, depot will be vertical, else horizontal. * @pre AIMap::IsValidTile(tile). - * @return whether the water depot has been/can be build or not. + * @return Whether the water depot has been/can be build or not. */ static bool BuildWaterDepot(TileIndex tile, bool vertical); /** * Builds a dock where tile is the tile still on land. - * @param tile the tile still on land of the dock. + * @param tile The tile still on land of the dock. * @pre AIMap::IsValidTile(tile). - * @return whether the dock has been/can be build or not. + * @return Whether the dock has been/can be build or not. */ static bool BuildDock(TileIndex tile); /** * Builds a buoy on tile. - * @param tile the tile where the buoy will be build. + * @param tile The tile where the buoy will be build. * @pre AIMap::IsValidTile(tile). - * @return whether the buoy has been/can be build or not. + * @return Whether the buoy has been/can be build or not. */ static bool BuildBuoy(TileIndex tile); /** * Builds a lock on tile. - * @param tile the tile where the lock will be build. + * @param tile The tile where the lock will be build. * @pre AIMap::IsValidTile(tile). - * @return whether the lock has been/can be build or not. + * @return Whether the lock has been/can be build or not. */ static bool BuildLock(TileIndex tile); /** * Builds a canal on tile. - * @param tile the tile where the canal will be build. + * @param tile The tile where the canal will be build. * @pre AIMap::IsValidTile(tile). - * @return whether the canal has been/can be build or not. + * @return Whether the canal has been/can be build or not. */ static bool BuildCanal(TileIndex tile); /** * Removes a water depot. - * @param tile any tile of the water depot. + * @param tile Any tile of the water depot. * @pre AIMap::IsValidTile(tile). - * @return whether the water depot has been/can be removed or not. + * @return Whether the water depot has been/can be removed or not. */ static bool RemoveWaterDepot(TileIndex tile); /** * Removes a dock. - * @param tile any tile of the dock. + * @param tile Any tile of the dock. * @pre AIMap::IsValidTile(tile). - * @return whether the dock has been/can be removed or not. + * @return Whether the dock has been/can be removed or not. */ static bool RemoveDock(TileIndex tile); /** * Removes a buoy. - * @param tile any tile of the buoy. + * @param tile Any tile of the buoy. * @pre AIMap::IsValidTile(tile). - * @return whether the buoy has been/can be removed or not. + * @return Whether the buoy has been/can be removed or not. */ static bool RemoveBuoy(TileIndex tile); /** * Removes a lock. - * @param tile any tile of the lock. + * @param tile Any tile of the lock. * @pre AIMap::IsValidTile(tile). - * @return whether the lock has been/can be removed or not. + * @return Whether the lock has been/can be removed or not. */ static bool RemoveLock(TileIndex tile); /** * Removes a canal. - * @param tile any tile of the canal. + * @param tile Any tile of the canal. * @pre AIMap::IsValidTile(tile). - * @return whether the canal has been/can be removed or not. + * @return Whether the canal has been/can be removed or not. */ static bool RemoveCanal(TileIndex tile); };