(svn r20318) -Doc: Doxygen additions.

src/company_base.h

@@ -43,30 +43,30 @@ struct CompanyProperties {
 	uint32 president_name_2; ///< Parameter of #president_name_1
 	char *president_name;    ///< Name of the president if the user changed it.
 
-	CompanyManagerFace face;
+	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.
-	Money current_loan;
+	Money current_loan;              ///< Amount of money borrowed from the bank.
 
-	byte colour;
+	byte colour;                     ///< Company colour.
 
-	RailTypes avail_railtypes;
+	RailTypes avail_railtypes;       ///< Rail types available to the company.
 
-	byte block_preview;
+	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
 
 	TileIndex location_of_HQ; ///< northern tile of HQ; INVALID_TILE when there is none
-	TileIndex last_build_coordinate;
+	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.
 
 	Year inaugurated_year;     ///< Year of starting the company.
 
-	byte quarters_of_bankruptcy;
+	byte quarters_of_bankruptcy;     ///< Number of quarters (a quarter is 3 months) that the company has a negative balance.
 	CompanyMask bankrupt_asked; ///< which companies were asked about buying it?
-	int16 bankrupt_timeout;
+	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).
@@ -90,12 +90,12 @@ struct Company : CompanyPool::PoolItem<&_company_pool>, CompanyProperties {
 	~Company();
 
 	Livery livery[LS_END];
-	RoadTypes avail_roadtypes;
+	RoadTypes avail_roadtypes;         ///< Road types available to this company.
 
 	class AIInstance *ai_instance;
 	class AIInfo *ai_info;
 
-	EngineRenewList engine_renew_list;
+	EngineRenewList engine_renew_list; ///< Engine renewals of this company.
 	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)
 

src/company_cmd.cpp

@@ -47,6 +47,11 @@ uint _cur_company_tick_index;             ///< used to generate a name for one c
 CompanyPool _company_pool("Company"); ///< Pool of companies.
 INSTANTIATE_POOL_METHODS(Company)
 
+/**
+ * Constructor.
+ * @param name_1 Name of the company.
+ * @param is_ai  A computer program is running for this company.
+ */
 Company::Company(uint16 name_1, bool is_ai)
 {
 	this->name_1 = name_1;
@@ -56,6 +61,7 @@ Company::Company(uint16 name_1, bool is_ai)
 	InvalidateWindowData(WC_PERFORMANCE_DETAIL, 0, INVALID_COMPANY);
 }
 
+/** Destructor. */
 Company::~Company()
 {
 	free(this->num_engines);

src/economy.cpp

@@ -481,6 +481,10 @@ void ChangeOwnershipOfCompanyItems(Owner old_owner, Owner new_owner)
 	MarkWholeScreenDirty();
 }
 
+/**
+ * Check for bankruptcy of a company. Called every three months.
+ * @param c Company to check.
+ */
 static void CompanyCheckBankrupt(Company *c)
 {
 	/*  If the company has money again, it does not go bankrupt */
@@ -552,6 +556,10 @@ static void CompanyCheckBankrupt(Company *c)
 	}
 }
 
+/**
+ * Update the finances of all companies.
+ * Pay for the stations, update the history graph, update ratings and company values, and deal with bankruptcy.
+ */
 static void CompaniesGenStatistics()
 {
 	Station *st;

src/engine.cpp

@@ -207,6 +207,10 @@ uint Engine::GetDisplayDefaultCapacity(uint16 *mail_capacity) const
 	}
 }
 
+/**
+ * Return how much the running costs of this engine are.
+ * @return Yearly running cost of the engine.
+ */
 Money Engine::GetRunningCost() const
 {
 	Price base_price;
@@ -240,6 +244,10 @@ Money Engine::GetRunningCost() const
 	return GetPrice(base_price, cost_factor, this->grffile, -8);
 }
 
+/**
+ * Return how much a new engine costs.
+ * @return Cost of the engine.
+ */
 Money Engine::GetCost() const
 {
 	Price base_price;
@@ -500,6 +508,7 @@ static void CalcEngineReliability(Engine *e)
 	SetWindowClassesDirty(WC_REPLACE_VEHICLE);
 }
 
+/** Compute the value for #_year_engine_aging_stops. */
 void SetYearEngineAgingStops()
 {
 	/* Determine last engine aging year, default to 2050 as previously. */
@@ -598,6 +607,11 @@ static void AcceptEnginePreview(EngineID eid, CompanyID company)
 	}
 }
 
+/**
+ * Get the N-th best company.
+ * @param pp Value N, 1 means best, 2 means second best, etc.
+ * @return N-th best company if it exists, #INVALID_COMPANY otherwise.
+ */
 static CompanyID GetBestCompany(uint8 pp)
 {
 	CompanyID best_company;
@@ -624,6 +638,7 @@ static CompanyID GetBestCompany(uint8 pp)
 	return best_company;
 }
 
+/** Daily check to offer an exclusive engine preview to the companies. */
 void EnginesDailyLoop()
 {
 	if (_cur_year >= _year_engine_aging_stops) return;
@@ -675,6 +690,11 @@ CommandCost CmdWantEnginePreview(TileIndex tile, DoCommandFlag flags, uint32 p1,
 	return CommandCost();
 }
 
+/**
+ * An engine has become available for general use.
+ * Also handle the exclusive engine preview contract.
+ * @param e Engine generally available as of now.
+ */
 static void NewVehicleAvailable(Engine *e)
 {
 	Vehicle *v;

src/newgrf_station.cpp

@@ -387,7 +387,7 @@ static struct {
 	uint32 v46;
 	uint32 v47;
 	uint32 v49;
-	uint8 valid;
+	uint8 valid; ///< Bits indicating what variable is valid (for each bit, \c 0 is invalid, \c 1 is valid).
 } _svc;
 
 static uint32 StationGetVariable(const ResolverObject *object, byte variable, byte parameter, bool *available)

src/newgrf_station.h

@@ -44,6 +44,7 @@ enum StationSpecFlags {
  * where index is computed as (x * platforms) + platform. */
 typedef byte *StationLayout;
 
+/** Station specification. */
 struct StationSpec {
 	const struct GRFFile *grffile; ///< ID of GRF file station belongs to.
 	int localidx; ///< Index within GRF file of station.