# HG changeset patch # User truelight # Date 1174176051 0 # Node ID 2a4c4340233d37dfba41a64458b861b3650b5779 # Parent 8f3c1bc72204001bf35f593fdc796568c994a528 (svn r9273) [NoAI] -Documentation: finished documenting the last few files; they should now be readable for any non-programmer. diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_company.hpp --- a/src/ai/api/ai_company.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_company.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -42,7 +42,7 @@ /** * Gets the amount your company have loaned. * @return the amount loaned money. - * @post the return value is always positive. + * @post the return value is always non-negative. * @post GetLoanInterval() is always a multiplier of the return value. */ int32 GetLoanAmount(); @@ -50,7 +50,7 @@ /** * Gets the maximum amount your company can loan. * @return the maximum amount your company can loan. - * @post the return value is always positive. + * @post the return value is always non-negative. * @post GetLoanInterval() is always a multiplier of the return value. */ int32 GetMaxLoanAmount(); @@ -65,10 +65,10 @@ /** * Sets the amount to loan. * @param loan the amount to loan (multiplier of GetLoanInterval()). - * @pre loan must be positive. + * @pre loan must be non-negative. * @pre GetLoanInterval must be a multiplier of loan. * @pre loan must be below GetMaxLoan(). - * @pre loan - GetLoanAmount() + GetBankBalance() must be positive. + * @pre loan - GetLoanAmount() + GetBankBalance() must be non-negative. * @return true if the loan could be set to your requested amount. */ bool SetLoanAmount(int32 loan); diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_controller.hpp --- a/src/ai/api/ai_controller.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_controller.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -7,45 +7,67 @@ #include "../../stdafx.h" +/** + * Class that handles the core of every AI. Each AI needs to extend this class + * in order to work. The OpenTTD core makes sure GetTick gets increased when + * needed. + */ class AIController { private: uint tick; public: + /** + * Initializer of the AIController. + */ AIController() : tick(0) {} + /** + * Destructor of the AIController. + */ virtual ~AIController() { } /** - * This function is called once to start the AI. + * This function is called to start your AI. Your AI starts here. If you + * return from this function, your AI dies, so make sure that doesn't + * happen. It is okay to use while() {} loops, as long as you put a + * Sleep() in it to give the rest of the game time to do things. Also + * don't keep the system busy for too long, as people will consider + * that annoying. + * @note Cannot be called from within your AI. */ virtual void Start() = 0; /** - * When this function is called, the AI must stop - * as soon as possible. It may not call any function - * that might suspend, like DoCommand and Sleep. - * @note This is only called when the AI is currently - * in a suspended state. + * When this function is called, the AI must stop as soon as possible. + * It may not call any function that might suspend, like DoCommand() + * and Sleep(). + * @note Cannot be called from within your AI. */ virtual void Stop() = 0; /** - * Increase the internal ticker. + * Increase the internal ticker. You should never call this yourself, + * as it is called by the OpenTTD system itself. + * @note Cannot be called from within your AI. */ void IncreaseTick() { this->tick++; } /** - * Return the value of the ticker. + * Find at which tick your AI currently is. + * @return returns the current tick. */ uint GetTick() { return this->tick; } /** * Sleep for X ticks. The code continues after this line when the X AI ticks - * are passed. Mind that an AI tick is different from in-game ticks and - * differ per AI speed. + * are passed. Mind that an AI tick is different from in-game ticks and + * differ per AI speed. + * @param ticks the ticks to wait + * @post the value of GetTick() will be changed exactly 'ticks' in value after + * calling this. */ void Sleep(uint ticks); }; diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_industry.hpp --- a/src/ai/api/ai_industry.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_industry.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -7,44 +7,49 @@ #include "ai_object.hpp" +/** + * Class that handles all industry related functions. + */ class AIIndustry : public AIObject { public: /** - * Gets the maximum industry index; there are no valid industries with a higher index - * @return the maximum town index - * @post return >= 0 + * 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. */ IndustryID GetMaxIndustryID(); /** - * Gets the number of industries - * @return the number of industries - * @post return >= 0 + * 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. */ 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 + * 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. */ bool IsValidIndustry(IndustryID industry_id); /** - * Get the name of the industry - * @param industry_id the industry to get the name of - * @pre this->IsValidIndustry(industry_id) - * @return the name of the industry - * @note the returned name must be freed + * 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). */ char *GetName(IndustryID industry_id); /** - * Gets the location of the industry - * @param industry_id the location of the industry - * @pre this->IsValidIndustry(industry_id) - * @return the location of the industry - * @post return >= 0 + * Gets the location of the industry. + * @param industry_id the location of the industry. + * @pre industry_id has to be valid (use IsValidIndustry()). + * @return the location of the industry. + * @post return value is always positive and below AIMap::GetMapSize(). */ TileIndex GetLocation(IndustryID industry_id); }; diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_map.hpp --- a/src/ai/api/ai_map.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_map.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -7,51 +7,54 @@ #include "ai_object.hpp" +/** + * Class that handles all map related functions. + */ class AIMap : public AIObject { public: /** - * 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 + * 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. */ bool IsValidTile(TileIndex t); /** - * Gets the number of tiles in the map - * @return the size of the map in tiles - * @post return > 0 + * Gets the number of tiles in the map. + * @return the size of the map in tiles. + * @post return value is always positive. */ TileIndex GetMapSize(); /** - * Gets the amount of tiles along the SW and NE border - * @return the length along the SW and NE borders - * @post return > 0 + * 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. */ uint32 GetMapSizeX(); /** - * Gets the amount of tiles along the SE and NW border - * @return the length along the SE and NW borders - * @post return > 0 + * 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. */ uint32 GetMapSizeY(); /** - * Gets the X (place along the SW/NE border) - * @param t the tile to get the X of - * @pre this->IsValidTile(t) - * @return the x-position - * @post return <= this->GetMapSizeX() + * 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(). */ uint32 GetTileX(TileIndex t); /** - * Gets the Y (place along the SE/NW border) - * @param t the tile to get the Y of - * @pre this->IsValidTile(t) - * @return the y-position - * @post return <= this->GetMapSizeY() + * 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(). */ uint32 GetTileY(TileIndex t); }; diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_object.hpp --- a/src/ai/api/ai_object.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_object.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -8,6 +8,12 @@ #include "../../stdafx.h" #include "../../functions.h" +/** + * Uper-parent object of all API classes. You should never use this class in + * your AI, as it doesn't publish any public functions. It is used + * internally to have a common place to handle general things, like internal + * command processing, and command-validation checks. + */ class AIObject { protected: /** diff -r 8f3c1bc72204 -r 2a4c4340233d src/ai/api/ai_town.hpp --- a/src/ai/api/ai_town.hpp Sat Mar 17 23:02:33 2007 +0000 +++ b/src/ai/api/ai_town.hpp Sun Mar 18 00:00:51 2007 +0000 @@ -7,53 +7,57 @@ #include "ai_object.hpp" +/** + * Class that handles all town related functions. + */ class AITown : public AIObject { public: /** - * Gets the maximum town index; there are no valid towns with a higher index - * @return the maximum town index - * @post return >= 0 + * 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. */ TownID GetMaxTownID(); /** - * Gets the number of towns - * @return the number of towns - * @post return >= 0 + * 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. */ 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 + * 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. */ bool IsValidTown(TownID town_id); /** - * Get the name of the town - * @param town_id the town to get the name of - * @pre this->IsValidTown(town) - * @return the name of the town - * @note the returned name must be freed + * 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). */ char *GetName(TownID town_id); /** - * Gets the number of inhabitants in the town - * @param town_id the town to get the name of - * @pre this->IsValidTown(town_id) - * @return the number of inhabitants - * @post return >= 0 + * 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. */ int32 GetPopulation(TownID town_id); /** - * Gets the location of the town - * @param town_id the location of the town - * @pre this->IsValidTown(town_id) - * @return the location of the town - * @post return >= 0 + * 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 positive and below AIMap::GetMapSize(). */ TileIndex GetLocation(TownID town_id); };