gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-03-06 14:27:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

(svn r20279) -Doc: Doxygen additions/improvements.

Browse Source
This commit is contained in:
alberth 2010-08-01 17:45:53 +00:00
parent 2d25def2ff
commit dc6ed2c2c0
10 changed files with 161 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
src/company_base.h
View File

@ -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;

67
src/company_cmd.cpp
View File

@ -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;

9
src/company_func.h
View File

@ -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;

10
src/date.cpp
View File

@ -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

3
src/economy.cpp
View File

@ -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();

10
src/industry_cmd.cpp
View File

@ -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;

11
src/newgrf_industrytiles.h
View File

@ -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);

4
src/strings.cpp
View File

@ -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?

19
src/town.h
View File

@ -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();

27
src/town_cmd.cpp
View File

@ -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) {