--- 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.
*/