diff -r 9abe20fc83e5 -r 2541c2d325ed src/ai/api/ai_company.hpp --- a/src/ai/api/ai_company.hpp Mon Mar 31 06:48:59 2008 +0000 +++ b/src/ai/api/ai_company.hpp Mon Mar 31 07:21:39 2008 +0000 @@ -14,130 +14,126 @@ public: static const char *GetClassName() { return "AICompany"; } - /** Different constants related to companies */ + /** Different constants related to CompanyIndex. */ enum CompanyIndex { FIRST_COMPANY = 0, ///< The first available company. LAST_COMPANY = 7, ///< The last available company. MY_COMPANY = 8, ///< Constant that gets resolved to the correct company index for your company. - INVALID_COMPANY = 9, ///< An invalid company + INVALID_COMPANY = 9, ///< An invalid company. }; /** - * Resolved the given company index to the correct index - * for the company. If the company index was MY_COMPANY - * it will be resolved to the index of your company. - * If the company with the given index does not exist - * it will return INVALID_COMPANY. - * @param company the company index to resolve. - * @return the resolved company index. + * Resolved the given company index to the correct index for the company. If + * the company index was MY_COMPANY it will be resolved to the index of + * your company. If the company with the given index does not exist it will + * return INVALID_COMPANY. + * @param company The company index to resolve. + * @return The resolved company index. */ static CompanyIndex ResolveCompanyIndex(CompanyIndex company); /** * Set the name of your company. - * @param name the new name of the company. - * @pre name != NULL - * @return true if the name was changed. + * @param name The new name of the company. + * @return True if the name was changed. */ static bool SetCompanyName(const char *name); /** * Get the name of the given company. - * @param company the company to get the name for. + * @param company The company to get the name for. * @pre ResolveCompanyIndex(company) != INVALID_COMPANY - * @return the name of the given company. - * @note the returned company name must be free'd (C++ only). + * @return The name of the given company. */ static char *GetCompanyName(CompanyIndex company); /** * Set the name of your president. - * @param name the new name of the president. - * @pre name != NULL - * @return true if the name was changed. + * @param name The new name of the president. + * @return True if the name was changed. */ static bool SetPresidentName(const char *name); /** * Get the name of the president of the given company. - * @param company the company to get the president's name for. + * @param company The company to get the president's name for. * @pre ResolveCompanyIndex(company) != INVALID_COMPANY - * @return the name of the president of the given company. - * @note the returned president name must be free'd (C++ only). + * @return The name of the president of the given company. */ static char *GetPresidentName(CompanyIndex company); /** * Sets the amount to loan. - * @param loan the amount to loan (multiplier of GetLoanInterval()). - * @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 non-negative. - * @return true if the loan could be set to your requested amount. + * @param loan The amount to loan (multiplier of GetLoanInterval()). + * @pre 'loan' must be non-negative. + * @pre GetLoanInterval() must be a multiplier of GetLoanInterval(). + * @pre 'loan' must be below GetMaxLoanAmount(). + * @pre 'loan' - GetLoanAmount() + GetBankBalance() must be non-negative. + * @return True if the loan could be set to your requested amount. */ static bool SetLoanAmount(int32 loan); /** * Sets the minimum amount to loan, i.e. the given amount of loan rounded up. - * @param loan the amount to loan (any positive number). - * @pre loan must be non-negative. - * @pre loan must be below GetMaxLoan(). - * @return true if we could allocate a minimum of "loan" loan. + * @param loan The amount to loan (any positive number). + * @pre 'loan' must be non-negative. + * @pre 'loan' must be below GetMaxLoanAmount(). + * @return True if we could allocate a minimum of "loan" loan. */ static bool SetMinimumLoanAmount(int32 loan); /** * Gets the amount your company have loaned. - * @return the amount loaned money. - * @post the return value is always non-negative. + * @return The amount loaned money. + * @post The return value is always non-negative. * @post GetLoanInterval() is always a multiplier of the return value. */ static int32 GetLoanAmount(); /** * Gets the maximum amount your company can loan. - * @return the maximum amount your company can loan. - * @post the return value is always non-negative. + * @return The maximum amount your company can loan. + * @post The return value is always non-negative. * @post GetLoanInterval() is always a multiplier of the return value. */ static int32 GetMaxLoanAmount(); /** * Gets the interval/loan step. - * @return the loan step. - * @post return value is always positive. + * @return The loan step. + * @post Return value is always positive. */ static int32 GetLoanInterval(); /** * Gets the current value of the given company. - * @param company the company to get the company value of. + * @param company The company to get the company value of. * @pre ResolveCompanyIndex(company) != INVALID_COMPANY - * @return the current value of the given company. + * @return The current value of the given company. */ static int32 GetCompanyValue(CompanyIndex company); /** * Gets the bank balance. In other words, the amount of money the given company can spent. - * @param company the company to get the bank balance of. + * @param company The company to get the bank balance of. * @pre ResolveCompanyIndex(company) != INVALID_COMPANY - * @return the actual bank balance. + * @return The actual bank balance. */ static int32 GetBankBalance(CompanyIndex company); /** * Build your company's HQ on the given tile. - * @param tile the tile to build your HQ on, this tile is the most nothern tile of your HQ. + * @param tile The tile to build your HQ on, this tile is the most nothern tile of your HQ. * @pre AIMap::IsValidTile(tile). - * @note An HQ can not be removed, only by water or rebuilding; If an HQ is build again, the old one is removed. - * @return true if the HQ could be build. + * @return True if the HQ could be build. + * @note An HQ can not be removed, only by water or rebuilding; If an HQ is + * build again, the old one is removed. */ static bool BuildCompanyHQ(TileIndex tile); /** * Return the location of a company's HQ. - * @param company the company the get the HQ of. + * @param company The company the get the HQ of. * @pre ResolveCompanyIndex(company) != INVALID_COMPANY. * @return The tile of the company's HQ, this tile is the most nothern tile of that HQ, or INVALID_TILE if there is no HQ yet. */