(svn r20320) -Doc: Small Doxygen and normal comment fixes, and an missed addition.

src/company_base.h

@@ -36,17 +36,17 @@ extern CompanyPool _company_pool;
 /** Statically loadable part of Company pool item */
 struct CompanyProperties {
 	uint32 name_2;                   ///< Parameter of #name_1.
-	uint16 name_1;                   ///< Name of the company
+	uint16 name_1;                   ///< Name of the company if the user did not change it.
 	char *name;                      ///< Name of the company if the user changed it.
 
-	uint16 president_name_1;         ///< Name of the president.
+	uint16 president_name_1;         ///< Name of the president if the user did not change it.
 	uint32 president_name_2;         ///< Parameter of #president_name_1
 	char *president_name;            ///< Name of the president if the user changed it.
 
 	CompanyManagerFace face;         ///< Face description of the president.
 
 	Money money;                     ///< Money owned by the company.
-	byte money_fraction;             ///< Fraction of money of the company, too small to represent in \a money.
+	byte money_fraction;             ///< Fraction of money of the company, too small to represent in #money.
 	Money current_loan;              ///< Amount of money borrowed from the bank.
 
 	byte colour;                     ///< Company colour.
@@ -55,9 +55,9 @@ struct CompanyProperties {
 
 	byte block_preview;              ///< Number of months that the company is not allowed to get new exclusive engine previews.
 
-	uint32 cargo_types;              ///< which cargo types were transported the last year
+	uint32 cargo_types;              ///< Which cargo types were transported the last year.
 
-	TileIndex location_of_HQ;        ///< northern tile of HQ; INVALID_TILE when there is none
+	TileIndex location_of_HQ;        ///< Northern tile of HQ; #INVALID_TILE when there is none.
 	TileIndex last_build_coordinate; ///< Coordinate of the last build thing by this company.
 
 	OwnerByte share_owners[4];       ///< Owners of the 4 shares of the company. #INVALID_OWNER if nobody has bought them yet.
@@ -69,10 +69,14 @@ struct CompanyProperties {
 	int16 bankrupt_timeout;          ///< If bigger than \c 0, amount of time to wait for an answer on an offer to buy this company.
 	Money bankrupt_value;
 
-	bool is_ai; ///< If \c true, the company is controlled by the computer (a NoAI program).
+	/**
+	 * If \c true, the company is (also) controlled by the computer (a NoAI program).
+	 * @note It is possible that the user is also participating in such a company.
+	 */
+	bool is_ai;
 
 	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 cur_economy;                     ///< Economic data of the company of this quarter.
 	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.
 
@@ -111,7 +115,7 @@ struct Company : CompanyPool::PoolItem<&_company_pool>, CompanyProperties {
 	}
 
 	/**
-	 * Is this company a valid company, controlled by a human (possibly another one than the user)?
+	 * Is this company a valid company, not controlled by a NoAI program?
 	 * @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.
@@ -123,7 +127,7 @@ struct Company : CompanyPool::PoolItem<&_company_pool>, CompanyProperties {
 	}
 
 	/**
-	 * Is this company a company controlled by a human (possibly another one than the user)?
+	 * Is this company a company not controlled by a NoAI program?
 	 * @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.

src/economy.cpp

@@ -523,7 +523,7 @@ static void CompanyCheckBankrupt(Company *c)
 				free(cni);
 				break;
 			}
-			/* Else, falltrue to case 4... */
+			/* FALL THROUGH to case 4... */
 		}
 		default:
 		case 4:
@@ -695,6 +695,7 @@ void RecomputePrices()
 	SetWindowDirty(WC_PAYMENT_RATES, 0);
 }
 
+/** Let all companies pay the monthly interest on their loan. */
 static void CompaniesPayInterest()
 {
 	const Company *c;
@@ -1349,7 +1350,7 @@ static void LoadUnloadVehicle(Vehicle *v, int *cargo_left)
 				/* if the aircraft carries passengers and is NOT full, then
 				 * continue loading, no matter how much mail is in */
 				if ((v->type == VEH_AIRCRAFT && IsCargoInClass(v->cargo_type, CC_PASSENGERS) && v->cargo_cap > v->cargo.Count()) ||
-						(cargo_not_full && (cargo_full & ~cargo_not_full) == 0)) { // There are still non-full cargos
+						(cargo_not_full && (cargo_full & ~cargo_not_full) == 0)) { // There are still non-full cargoes
 					finished_loading = false;
 				}
 			} else if (cargo_not_full != 0) {

src/genworld.cpp

@@ -74,8 +74,8 @@ bool IsGenerateWorldThreaded()
 }
 
 /**
- * Clean up the 'mess' of generation. That is show windows again, reset
- * thread variables and delete the progress window.
+ * Clean up the 'mess' of generation. That is, show windows again, reset
+ * thread variables, and delete the progress window.
  */
 static void CleanupGeneration()
 {

src/industry_cmd.cpp

@@ -1689,7 +1689,7 @@ static void DoCreateNewIndustry(Industry *i, TileIndex tile, IndustryType type,
  * @param seed random seed (possibly) used by industries
  * @param initial_random_bits The random bits the industry is going to have after construction.
  * @param founder Founder of the industry
- * @param ip Pointer to store newly created industry.
+ * @param [out] ip Pointer to store newly created industry.
  * @return Succeeded or failed command.
  *
  * @post \c *ip contains the newly created industry if all checks are successful and the \a flags request actual creation, else it contains \c NULL afterwards.
@@ -1971,7 +1971,7 @@ static void UpdateIndustryStatistics(Industry *i)
 /** Simple helper that will collect data for the generation of industries */
 struct ProbabilityHelper {
 	uint16 prob;      ///< probability
-	IndustryType ind; ///< industry id correcponding
+	IndustryType ind; ///< Industry id.
 };
 
 /**

src/town.h

@@ -171,7 +171,7 @@ enum TownRatingCheckType {
 static const byte TOWN_GROWTH_FREQUENCY = 70;
 
 /**
- * This enum is used in conjonction with town->flags.
+ * This enum is used in conjunction with town->flags.
  * IT simply states what bit is used for.
  * It is pretty unrealistic (IMHO) to only have one church/stadium
  * per town, NO MATTER the population of it.

src/town_cmd.cpp

@@ -2822,12 +2822,12 @@ static int GetRating(const Town *t)
  * Changes town rating of the current company
  * @param t Town to affect
  * @param add Value to add
- * @param max Minimum (add < 0) resp. maximum (add > 0) rating that should be archievable with this change
+ * @param max Minimum (add < 0) resp. maximum (add > 0) rating that should be achievable with this change.
  * @param flags Command flags, especially DC_NO_MODIFY_TOWN_RATING is tested
  */
 void ChangeTownRating(Town *t, int add, int max, DoCommandFlag flags)
 {
-	/* if magic_bulldozer cheat is active, town doesn't penaltize for removing stuff */
+	/* if magic_bulldozer cheat is active, town doesn't penalize for removing stuff */
 	if (t == NULL || (flags & DC_NO_MODIFY_TOWN_RATING) ||
 			!Company::IsValidID(_current_company) ||
 			(_cheats.magic_bulldozer.value && add < 0)) {