--- 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);
};
--- 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);
--- 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 */
--- 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);
};