summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2010-08-01 17:45:53 +0000
committeralberth <alberth@openttd.org>2010-08-01 17:45:53 +0000
commitdc6ed2c2c02a651a50b2d2b232302d0c7eab48ec (patch)
tree29a7c1aa361bf156c083f5d295bf973da8867db9
parent2d25def2ff7617a4f800d16eacce704395d962cf (diff)
downloadopenttd-dc6ed2c2c02a651a50b2d2b232302d0c7eab48ec.tar.xz
(svn r20279) -Doc: Doxygen additions/improvements.
-rw-r--r--src/company_base.h52
-rw-r--r--src/company_cmd.cpp67
-rw-r--r--src/company_func.h9
-rw-r--r--src/date.cpp10
-rw-r--r--src/economy.cpp3
-rw-r--r--src/industry_cmd.cpp10
-rw-r--r--src/newgrf_industrytiles.h11
-rw-r--r--src/strings.cpp4
-rw-r--r--src/town.h19
-rw-r--r--src/town_cmd.cpp27
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) {