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

10 files changed, 161 insertions, 51 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;
diff --git a/src/company_cmd.cpp b/src/company_cmd.cpp
index 4c3449a28..a7578be1d 100644
--- a/src/company_cmd.cpp
+++ b/src/company_cmd.cpp
@@ -39,13 +39,12 @@
 
 CompanyByte _local_company;   ///< Company controlled by the human player at this client. Can also be #COMPANY_SPECTATOR.
 CompanyByte _current_company; ///< Company currently doing an action.
-/* NOSAVE: can be determined from company structs */
-Colours _company_colours[MAX_COMPANIES];
+Colours _company_colours[MAX_COMPANIES];  ///< NOSAVE: can be determined from company structs.
 CompanyManagerFace _company_manager_face; ///< for company manager face storage in openttd.cfg
 uint _next_competitor_start;              ///< the number of ticks before the next AI is started
 uint _cur_company_tick_index;             ///< used to generate a name for one company that doesn't have a name yet per tick
 
-CompanyPool _company_pool("Company");
+CompanyPool _company_pool("Company"); ///< Pool of companies.
 INSTANTIATE_POOL_METHODS(Company)
 
 Company::Company(uint16 name_1, bool is_ai)
@@ -106,14 +105,23 @@ void SetLocalCompany(CompanyID new_company)
 	MarkWholeScreenDirty();
 }
 
+/**
+ * Get the colour for DrawString-subroutines which matches the colour of the company.
+ * @param company Company to get the colour of.
+ * @return Colour of \a company.
+ */
 uint16 GetDrawStringCompanyColour(CompanyID company)
 {
-	/* Get the colour for DrawString-subroutines which matches the colour
-	 * of the company */
 	if (!Company::IsValidID(company)) return _colour_gradient[COLOUR_WHITE][4] | IS_PALETTE_COLOUR;
 	return (_colour_gradient[_company_colours[company]][4]) | IS_PALETTE_COLOUR;
 }
 
+/**
+ * Draw the icon of a company.
+ * @param c Company that needs its icon drawn.
+ * @param x Horizontal coordinate of the icon.
+ * @param y Vertical coordinate of the icon.
+ */
 void DrawCompanyIcon(CompanyID c, int x, int y)
 {
 	DrawSprite(SPR_COMPANY_ICON, COMPANY_SPRITE_COLOUR(c), x, y);
@@ -150,6 +158,10 @@ bool IsValidCompanyManagerFace(CompanyManagerFace cmf)
 	return true;
 }
 
+/**
+ * Refresh all windows owned by a company.
+ * @param company Company that changed, and needs its windows refreshed.
+ */
 void InvalidateCompanyWindows(const Company *company)
 {
 	CompanyID cid = company->index;
@@ -176,6 +188,11 @@ bool CheckCompanyHasMoney(CommandCost &cost)
 	return true;
 }
 
+/**
+ * Deduct costs of a command from the money of a company.
+ * @param c Company to pay the bill.
+ * @param cost Money to pay.
+ */
 static void SubtractMoneyFromAnyCompany(Company *c, CommandCost cost)
 {
 	if (cost.GetCost() == 0) return;
@@ -201,12 +218,21 @@ static void SubtractMoneyFromAnyCompany(Company *c, CommandCost cost)
 	InvalidateCompanyWindows(c);
 }
 
+/**
+ * Subtract money from the #_current_company, if the company is valid.
+ * @param cost Money to pay.
+ */
 void SubtractMoneyFromCompany(CommandCost cost)
 {
 	Company *c = Company::GetIfValid(_current_company);
 	if (c != NULL) SubtractMoneyFromAnyCompany(c, cost);
 }
 
+/**
+ * Subtract money from a company, including the money fraction.
+ * @param company Company paying the bill.
+ * @param cst     Cost of a command.
+ */
 void SubtractMoneyFromCompanyFract(CompanyID company, CommandCost cst)
 {
 	Company *c = Company::Get(company);
@@ -285,6 +311,10 @@ CommandCost CheckTileOwnership(TileIndex tile)
 	return_cmd_error(STR_ERROR_OWNED_BY);
 }
 
+/**
+ * Generate the name of a company from the last build coordinate.
+ * @param c Company to give a name.
+ */
 static void GenerateCompanyName(Company *c)
 {
 	TileIndex tile;
@@ -367,6 +397,10 @@ static const Colours _similar_colour[COLOUR_END][2] = {
 	{ COLOUR_GREY,       INVALID_COLOUR    }, // COLOUR_WHITE
 };
 
+/**
+ * Generate a company colour.
+ * @return Generated company colour.
+ */
 static Colours GenerateCompanyColour()
 {
 	Colours colours[COLOUR_END];
@@ -419,6 +453,10 @@ static Colours GenerateCompanyColour()
 	NOT_REACHED();
 }
 
+/**
+ * Generate a random president name of a company.
+ * @param c Company that needs a new president name.
+ */
 static void GeneratePresidentName(Company *c)
 {
 	for (;;) {
@@ -507,12 +545,14 @@ Company *DoStartupNewCompany(bool is_ai, CompanyID company = INVALID_COMPANY)
 	return c;
 }
 
+/** Start the next competitor now. */
 void StartupCompanies()
 {
 	_next_competitor_start = 0;
 }
 
 #ifdef ENABLE_AI
+/** Start a new competitor company if possible. */
 static void MaybeStartNewCompany()
 {
 #ifdef ENABLE_NETWORK
@@ -535,6 +575,7 @@ static void MaybeStartNewCompany()
 }
 #endif /* ENABLE_AI */
 
+/** Initialize the pool of companies. */
 void InitializeCompanies()
 {
 	_company_pool.CleanPool();
@@ -625,6 +666,10 @@ void OnTick_Companies()
 	_cur_company_tick_index = (_cur_company_tick_index + 1) % MAX_COMPANIES;
 }
 
+/**
+ * A year has passed, update the economic data of all companies, and perhaps show the
+ * financial overview window of the local company.
+ */
 void CompaniesYearlyLoop()
 {
 	Company *c;
@@ -650,7 +695,7 @@ void CompaniesYearlyLoop()
 /**
  * Fill the CompanyNewsInformation struct with the required data.
  * @param c the current company.
- * @param other the other company.
+ * @param other the other company (use \c NULL if not relevant).
  */
 void CompanyNewsInformation::FillData(const Company *c, const Company *other)
 {
@@ -936,6 +981,11 @@ CommandCost CmdSetCompanyColour(TileIndex tile, DoCommandFlag flags, uint32 p1,
 	return CommandCost();
 }
 
+/**
+ * Is the given name in use as name of a company?
+ * @param name Name to search.
+ * @return \c true if the name us unique (that is, not in use), else \c false.
+ */
 static bool IsUniqueCompanyName(const char *name)
 {
 	const Company *c;
@@ -974,6 +1024,11 @@ CommandCost CmdRenameCompany(TileIndex tile, DoCommandFlag flags, uint32 p1, uin
 	return CommandCost();
 }
 
+/**
+ * Is the given name in use as president name of a company?
+ * @param name Name to search.
+ * @return \c true if the name us unique (that is, not in use), else \c false.
+ */
 static bool IsUniquePresidentName(const char *name)
 {
 	const Company *c;
diff --git a/src/company_func.h b/src/company_func.h
index 8dcdffbe8..6fcf348f5 100644
--- a/src/company_func.h
+++ b/src/company_func.h
@@ -24,8 +24,8 @@ void ShowBuyCompanyDialog(CompanyID company);
 extern CompanyByte _local_company;
 extern CompanyByte _current_company;
 
-extern Colours _company_colours[MAX_COMPANIES];  ///< NOSAVE: can be determined from company structs
-extern CompanyManagerFace _company_manager_face; ///< for company manager face storage in openttd.cfg
+extern Colours _company_colours[MAX_COMPANIES];
+extern CompanyManagerFace _company_manager_face;
 
 /**
  * Is the current company the local company?
@@ -36,6 +36,11 @@ static inline bool IsLocalCompany()
 	return _local_company == _current_company;
 }
 
+/**
+ * Is the user representing \a company?
+ * @param company Company where interaction is needed with.
+ * @return Gives \c true if the user can answer questions interactively as representative of \a company, else \c false
+ */
 static inline bool IsInteractiveCompany(CompanyID company)
 {
 	return company == _local_company;
diff --git a/src/date.cpp b/src/date.cpp
index 3c29eaf82..bdf4dd0fc 100644
--- a/src/date.cpp
+++ b/src/date.cpp
@@ -27,6 +27,10 @@ Date      _date;       ///< Current date in days (day counter)
 DateFract _date_fract;
 uint16 _tick_counter;  ///< Ever incrementing (and sometimes wrapping) tick counter for setting off various events
 
+/**
+ * Set the date.
+ * @param date New date
+ */
 void SetDate(Date date)
 {
 	YearMonthDay ymd;
@@ -69,6 +73,7 @@ enum DaysTillMonth {
 	ACCUM_DEC = ACCUM_NOV + 30,
 };
 
+/** Number of days to pass from the first day in the year before reaching the first of a month. */
 static const uint16 _accum_days_for_month[] = {
 	ACCUM_JAN, ACCUM_FEB, ACCUM_MAR, ACCUM_APR,
 	ACCUM_MAY, ACCUM_JUN, ACCUM_JUL, ACCUM_AUG,
@@ -82,8 +87,7 @@ static const uint16 _accum_days_for_month[] = {
  */
 void ConvertDateToYMD(Date date, YearMonthDay *ymd)
 {
-	/*
-	 * Year determination in multiple steps to account for leap
+	/* Year determination in multiple steps to account for leap
 	 * years. First do the large steps, then the smaller ones.
 	 */
 
@@ -152,6 +156,7 @@ Date ConvertYMDToDate(Year year, Month month, Day day)
 extern void EnginesDailyLoop();
 extern void DisasterDailyLoop();
 extern void IndustryDailyLoop();
+
 extern void CompaniesMonthlyLoop();
 extern void EnginesMonthlyLoop();
 extern void TownsMonthlyLoop();
@@ -166,6 +171,7 @@ extern void TownsYearlyLoop();
 extern void ShowEndGameChart();
 
 
+/** Available settings for autosave intervals. */
 static const Month _autosave_months[] = {
 	 0, ///< never
 	 1, ///< every month
diff --git a/src/economy.cpp b/src/economy.cpp
index 6d35b35d3..a48eccb7d 100644
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -1423,6 +1423,9 @@ void LoadUnloadStation(Station *st)
 	_cargo_delivery_destinations.Clear();
 }
 
+/**
+ * Monthly update of the economic data (of the companies as well as economic fluctuations).
+ */
 void CompaniesMonthlyLoop()
 {
 	CompaniesGenStatistics();
diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
index 43b54b1ff..c3bb22baa 100644
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -1922,6 +1922,10 @@ void GenerateIndustries()
 	}
 }
 
+/**
+ * Monthly update of industry statistics.
+ * @param i Industry to update.
+ */
 static void UpdateIndustryStatistics(Industry *i)
 {
 	for (byte j = 0; j < lengthof(i->produced_cargo); j++) {
@@ -2363,11 +2367,13 @@ static void ChangeIndustryProduction(Industry *i, bool monthly)
 	}
 }
 
-/** Daily handler for the industry changes
+/**
+ * Daily handler for the industry changes
  * Taking the original map size of 256*256, the number of random changes was always of just one unit.
  * But it cannot be the same on smaller or bigger maps. That number has to be scaled up or down.
  * For small maps, it implies that less than one change per month is required, while on bigger maps,
- * it would be way more. The daily loop handles those changes. */
+ * it would be way more. The daily loop handles those changes.
+ */
 void IndustryDailyLoop()
 {
 	_economy.industry_daily_change_counter += _economy.industry_daily_increment;
diff --git a/src/newgrf_industrytiles.h b/src/newgrf_industrytiles.h
index 86a625359..ba2d9ac9b 100644
--- a/src/newgrf_industrytiles.h
+++ b/src/newgrf_industrytiles.h
@@ -17,6 +17,7 @@
 #include "newgrf_callbacks.h"
 #include "core/random_func.hpp"
 
+/** Animation triggers of the industries. */
 enum IndustryAnimationTrigger {
 	IAT_CONSTRUCTION_STATE_CHANGE,
 	IAT_TILELOOP,
@@ -34,13 +35,11 @@ bool StartStopIndustryTileAnimation(TileIndex tile, IndustryAnimationTrigger iat
 bool StartStopIndustryTileAnimation(const Industry *ind, IndustryAnimationTrigger iat);
 
 
+/** Available industry tile triggers. */
 enum IndustryTileTrigger {
-	/* The tile of the industry has been triggered during the tileloop. */
-	INDTILE_TRIGGER_TILE_LOOP       = 0x01,
-	/* The industry has been triggered via its tick. */
-	INDUSTRY_TRIGGER_INDUSTRY_TICK  = 0x02,
-	/* Cargo has been delivered. */
-	INDUSTRY_TRIGGER_RECEIVED_CARGO = 0x04,
+	INDTILE_TRIGGER_TILE_LOOP       = 0x01, ///< The tile of the industry has been triggered during the tileloop.
+	INDUSTRY_TRIGGER_INDUSTRY_TICK  = 0x02, ///< The industry has been triggered via its tick.
+	INDUSTRY_TRIGGER_RECEIVED_CARGO = 0x04, ///< Cargo has been delivered.
 };
 void TriggerIndustryTile(TileIndex t, IndustryTileTrigger trigger);
 void TriggerIndustry(Industry *ind, IndustryTileTrigger trigger);
diff --git a/src/strings.cpp b/src/strings.cpp
index 90019a495..be7340616 100644
--- a/src/strings.cpp
+++ b/src/strings.cpp
@@ -55,8 +55,8 @@ struct LanguagePack : public LanguagePackHeader {
 
 static char **_langpack_offs;
 static LanguagePack *_langpack;
-static uint _langtab_num[32];   // Offset into langpack offs
-static uint _langtab_start[32]; // Offset into langpack offs
+static uint _langtab_num[32];   ///< Offset into langpack offs
+static uint _langtab_start[32]; ///< Offset into langpack offs
 static bool _keep_gender_data = false;  ///< Should we retain the gender data in the current string?
 
 
diff --git a/src/town.h b/src/town.h
index 7b9bae1ce..ff1ba0214 100644
--- a/src/town.h
+++ b/src/town.h
@@ -32,6 +32,7 @@ static const uint INVALID_TOWN = 0xFFFF;
 typedef Pool<Town, TownID, 64, 64000> TownPool;
 extern TownPool _town_pool;
 
+/** Town data structure. */
 struct Town : TownPool::PoolItem<&_town_pool> {
 	TileIndex xy;
 
@@ -65,7 +66,7 @@ struct Town : TownPool::PoolItem<&_town_pool> {
 	uint8 unwanted[MAX_COMPANIES]; ///< how many months companies aren't wanted by towns (bribe)
 	CompanyByte exclusivity;       ///< which company has exclusivity
 	uint8 exclusive_counter;       ///< months till the exclusivity expires
-	int16 ratings[MAX_COMPANIES];
+	int16 ratings[MAX_COMPANIES];  ///< Ratings of each company for this town.
 
 	/* Maximum amount of passengers and mail that can be transported. */
 	uint32 max_pass;
@@ -109,8 +110,7 @@ struct Town : TownPool::PoolItem<&_town_pool> {
 	/* NOSAVE: UpdateTownRadius updates this given the house count. */
 	uint32 squared_town_zone_radius[HZB_END];
 
-	/* NOSAVE: The number of each type of building in the town. */
-	BuildingCounts<uint16> building_counts;
+	BuildingCounts<uint16> building_counts; ///< NOSAVE: The number of each type of building in the town.
 
 	/**
 	 * Creates a new town
@@ -122,17 +122,18 @@ struct Town : TownPool::PoolItem<&_town_pool> {
 
 	void InitializeLayout(TownLayout layout);
 
-	/** Calculate the max town noise
+	/**
+	 * Calculate the max town noise.
 	 * The value is counted using the population divided by the content of the
-	 * entry in town_noise_population corespondig to the town's tolerance.
-	 * To this result, we add 3, which is the noise of the lowest airport.
-	 * So user can at least buld that airport
-	 * @return the maximum noise level the town will tolerate */
+	 * entry in town_noise_population corresponding to the town's tolerance.
+	 * @return the maximum noise level the town will tolerate.
+	 */
 	inline uint16 MaxTownNoise() const
 	{
 		if (this->population == 0) return 0; // no population? no noise
 
-		return ((this->population / _settings_game.economy.town_noise_population[_settings_game.difficulty.town_council_tolerance]) + 3);
+		/* 3 is added (the noise of the lowest airport), so the  user can at least build a small airfield. */
+		return (this->population / _settings_game.economy.town_noise_population[_settings_game.difficulty.town_council_tolerance]) + 3;
 	}
 
 	void UpdateVirtCoord();
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
index bc831a69b..dd88b571a 100644
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -2705,7 +2705,7 @@ CommandCost CheckIfAuthorityAllowsNewStation(TileIndex tile, DoCommandFlag flags
 /** Return the town closest to the given tile within \a threshold.
  * @param tile      Starting point of the search.
  * @param threshold Biggest allowed distance to the town.
- * @return Closest town to \a tile withinh \a threshold, or \c NULL if there is no such town.
+ * @return Closest town to \a tile within \a threshold, or \c NULL if there is no such town.
  *
  * @note This function only uses distance, the #ClosestTownFromTile function also takes town ownership into account.
  */
@@ -2726,7 +2726,14 @@ Town *CalcClosestTownFromTile(TileIndex tile, uint threshold)
 	return best_town;
 }
 
-
+/**
+ * Return the town closest (in distance or ownership) to a given tile, within a given threshold.
+ * @param tile      Starting point of the search.
+ * @param threshold Biggest allowed distance to the town.
+ * @return Closest town to \a tile within \a threshold, or \c NULL if there is no such town.
+ *
+ * @note If you only care about distance, you can use the #CalcClosestTownFromTile function.
+ */
 Town *ClosestTownFromTile(TileIndex tile, uint threshold)
 {
 	switch (GetTileType(tile)) {
@@ -2760,12 +2767,17 @@ Town *ClosestTownFromTile(TileIndex tile, uint threshold)
 	}
 }
 
-static bool _town_rating_test = false;
-static SmallMap<const Town *, int, 4> _town_test_ratings;
+static bool _town_rating_test = false; ///< If \c true, town rating is in test-mode.
+static SmallMap<const Town *, int, 4> _town_test_ratings; ///< Map of towns to modified ratings, while in town rating test-mode.
 
+/**
+ * Switch the town rating to test-mode, to allow commands to be tested without affecting current ratings.
+ * The function is safe to use in nested calls.
+ * @param mode Test mode switch (\c true means go to test-mode, \c false means leave test-mode).
+ */
 void SetTownRatingTestMode(bool mode)
 {
-	static int ref_count = 0;
+	static int ref_count = 0; // Number of times test-mode is switched on.
 	if (mode) {
 		if (ref_count == 0) {
 			_town_test_ratings.Clear();
@@ -2778,6 +2790,11 @@ void SetTownRatingTestMode(bool mode)
 	_town_rating_test = !(ref_count == 0);
 }
 
+/**
+ * Get the rating of a town for the #_current_company.
+ * @param t Town to get the rating from.
+ * @return Rating of the current company in the given town.
+ */
 static int GetRating(const Town *t)
 {
 	if (_town_rating_test) {