From 5556955960c32780170b99259835502c052852fa Mon Sep 17 00:00:00 2001 From: alberth Date: Mon, 2 Aug 2010 20:32:39 +0000 Subject: (svn r20318) -Doc: Doxygen additions. --- src/company_base.h | 20 ++++++++++---------- src/company_cmd.cpp | 6 ++++++ src/economy.cpp | 8 ++++++++ src/engine.cpp | 20 ++++++++++++++++++++ src/newgrf_station.cpp | 2 +- src/newgrf_station.h | 1 + 6 files changed, 46 insertions(+), 11 deletions(-) diff --git a/src/company_base.h b/src/company_base.h index 887f1b715..eb85e1fa3 100644 --- a/src/company_base.h +++ b/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) diff --git a/src/company_cmd.cpp b/src/company_cmd.cpp index 25f5959b1..9df78ebe7 100644 --- a/src/company_cmd.cpp +++ b/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); diff --git a/src/economy.cpp b/src/economy.cpp index 2ea9a386a..cad7f50b4 100644 --- a/src/economy.cpp +++ b/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; diff --git a/src/engine.cpp b/src/engine.cpp index 91d53e786..7809af616 100644 --- a/src/engine.cpp +++ b/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; diff --git a/src/newgrf_station.cpp b/src/newgrf_station.cpp index 24c14ef10..209acaa1b 100644 --- a/src/newgrf_station.cpp +++ b/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) diff --git a/src/newgrf_station.h b/src/newgrf_station.h index c65a6be81..d42db176f 100644 --- a/src/newgrf_station.h +++ b/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. -- cgit v1.2.3-54-g00ecf