(svn r20279) -Doc: Doxygen additions/improvements.

1 files changed, 35 insertions, 17 deletions

diff --git a/src/company_base.h b/src/company_base.h
index e06bca433..887f1b715 100644
--- a/src/company_base.h
+++ b/src/company_base.h
@@ -35,18 +35,18 @@ extern CompanyPool _company_pool;
 
 /** Statically loadable part of Company pool item */
 struct CompanyProperties {
-	uint32 name_2;
-	uint16 name_1;
-	char *name;
+	uint32 name_2; ///< Parameter of #name_1.
+	uint16 name_1; ///< Name of the company
+	char *name;    ///< Name of the company if the user changed it.
 
-	uint16 president_name_1;
-	uint32 president_name_2;
-	char *president_name;
+	uint16 president_name_1; ///< Name of the president.
+	uint32 president_name_2; ///< Parameter of #president_name_1
+	char *president_name;    ///< Name of the president if the user changed it.
 
 	CompanyManagerFace face;
 
-	Money money;
-	byte money_fraction;
+	Money money;         ///< Money owned by the company.
+	byte money_fraction; ///< Fraction of money of the company, too small to represent in \a money.
 	Money current_loan;
 
 	byte colour;
@@ -60,21 +60,21 @@ struct CompanyProperties {
 	TileIndex location_of_HQ; ///< northern tile of HQ; INVALID_TILE when there is none
 	TileIndex last_build_coordinate;
 
-	OwnerByte share_owners[4];
+	OwnerByte share_owners[4]; ///< Owners of the 4 shares of the company. #INVALID_OWNER if nobody has bought them yet.
 
-	Year inaugurated_year;
-	byte num_valid_stat_ent;
+	Year inaugurated_year;     ///< Year of starting the company.
 
 	byte quarters_of_bankruptcy;
 	CompanyMask bankrupt_asked; ///< which companies were asked about buying it?
 	int16 bankrupt_timeout;
 	Money bankrupt_value;
 
-	bool is_ai;
+	bool is_ai; ///< If \c true, the company is controlled by the computer (a NoAI program).
 
-	Money yearly_expenses[3][EXPENSES_END];
-	CompanyEconomyEntry cur_economy;
-	CompanyEconomyEntry old_economy[MAX_HISTORY_MONTHS];
+	Money yearly_expenses[3][EXPENSES_END];              ///< Expenses of the company for the last three years, in every #Expenses category.
+	CompanyEconomyEntry cur_economy;                     ///< Economic data of the company of this year.
+	CompanyEconomyEntry old_economy[MAX_HISTORY_MONTHS]; ///< Economic data of the company of the last #MAX_HISTORY_MONTHS months.
+	byte num_valid_stat_ent;                             ///< Number of valid statistical entries in #old_economy.
 
 	CompanyProperties() : name(NULL), president_name(NULL) {}
 
@@ -95,22 +95,40 @@ struct Company : CompanyPool::PoolItem<&_company_pool>, CompanyProperties {
 	class AIInstance *ai_instance;
 	class AIInfo *ai_info;
 
-	EngineRenewList engine_renew_list; ///< Defined later
+	EngineRenewList engine_renew_list;
 	CompanySettings settings;          ///< settings specific for each company
-	uint16 *num_engines; ///< caches the number of engines of each type the company owns (no need to save this)
+	uint16 *num_engines;               ///< caches the number of engines of each type the company owns (no need to save this)
 
+	/**
+	 * Is this company a valid company, controlled by the computer (a NoAI program)?
+	 * @param index Index in the pool.
+	 * @return \c true if it is a valid, computer controlled company, else \c false.
+	 */
 	static FORCEINLINE bool IsValidAiID(size_t index)
 	{
 		const Company *c = Company::GetIfValid(index);
 		return c != NULL && c->is_ai;
 	}
 
+	/**
+	 * Is this company a valid company, controlled by a human (possibly another one than the user)?
+	 * @param index Index in the pool.
+	 * @return \c true if it is a valid, human controlled company, else \c false.
+	 * @note If you know that \a index refers to a valid company, you can use #IsHumanID() instead.
+	 */
 	static FORCEINLINE bool IsValidHumanID(size_t index)
 	{
 		const Company *c = Company::GetIfValid(index);
 		return c != NULL && !c->is_ai;
 	}
 
+	/**
+	 * Is this company a company controlled by a human (possibly another one than the user)?
+	 * @param index Index in the pool.
+	 * @return \c true if it is a human controlled company, else \c false.
+	 * @pre \a index must be a valid CompanyID.
+	 * @note If you don't know whether \a index refers to a valid company, you should use #IsValidHumanID() instead.
+	 */
 	static FORCEINLINE bool IsHumanID(size_t index)
 	{
 		return !Company::Get(index)->is_ai;