diff options
| -rw-r--r-- | src/company_base.h | 52 | ||||
| -rw-r--r-- | src/company_cmd.cpp | 67 | ||||
| -rw-r--r-- | src/company_func.h | 9 | ||||
| -rw-r--r-- | src/date.cpp | 10 | ||||
| -rw-r--r-- | src/economy.cpp | 3 | ||||
| -rw-r--r-- | src/industry_cmd.cpp | 10 | ||||
| -rw-r--r-- | src/newgrf_industrytiles.h | 11 | ||||
| -rw-r--r-- | src/strings.cpp | 4 | ||||
| -rw-r--r-- | src/town.h | 19 | ||||
| -rw-r--r-- | src/town_cmd.cpp | 27 |
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) { |