gronod/OpenTTD
1
0
Fork 0
mirror of https://github.com/OpenTTD/OpenTTD.git synced 2025-03-12 02:19:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

(svn r21845) -Codechange: move documentation towards the code to make it more likely to be updates [d-m].

Browse Source
This commit is contained in:
rubidium 2011-01-18 22:31:06 +00:00
parent 6c9078fd30
commit 7efd7e19ed
22 changed files with 144 additions and 185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
src/company_cmd.cpp
View File

@ -501,6 +501,11 @@ restart:;
}
}
/**
* Reset the livery schemes to the company's primary colour.
* This is used on loading games without livery information and on new company start up.
* @param c Company to reset.
*/
void ResetCompanyLivery(Company *c)
{
for (LiveryScheme scheme = LS_BEGIN; scheme < LS_END; scheme++) {

12
src/elrail.cpp
View File

@ -473,6 +473,13 @@ static void DrawCatenaryRailway(const TileInfo *ti)
}
}
/**
* Draws wires on a tunnel tile
*
* DrawTile_TunnelBridge() calls this function to draw the wires on the bridge.
*
* @param ti The Tileinfo to draw the tile for
*/
void DrawCatenaryOnBridge(const TileInfo *ti)
{
TileIndex end = GetSouthernBridgeEnd(ti->tile);
@ -530,6 +537,11 @@ void DrawCatenaryOnBridge(const TileInfo *ti)
}
}
/**
* Draws overhead wires and pylons for electric railways.
* @param ti The TileInfo struct of the tile being drawn
* @see DrawCatenaryRailway
*/
void DrawCatenary(const TileInfo *ti)
{
switch (GetTileType(ti->tile)) {

5
src/elrail_func.h
View File

@ -34,11 +34,6 @@ static inline bool HasCatenaryDrawn(RailType rt)
return HasCatenary(rt) && !IsInvisibilitySet(TO_CATENARY) && !_settings_game.vehicle.disable_elrails;
}
/**
* Draws overhead wires and pylons for electric railways.
* @param ti The TileInfo struct of the tile being drawn
* @see DrawCatenaryRailway
*/
void DrawCatenary(const TileInfo *ti);
void DrawCatenaryOnTunnel(const TileInfo *ti);
void DrawCatenaryOnBridge(const TileInfo *ti);

5
src/functions.h
View File

@ -28,11 +28,6 @@ CommandCost CheckOwnership(Owner owner, TileIndex tile = 0);
CommandCost CheckTileOwnership(TileIndex tile);
/* misc functions */
/**
* Mark a tile given by its index dirty for repaint.
*
* @ingroup dirty
*/
void MarkTileDirtyByTile(TileIndex tile);
void ShowCostOrIncomeAnimation(int x, int y, int z, Money cost);

7
src/gfx.cpp
View File

@ -1559,7 +1559,7 @@ void RedrawScreenRect(int left, int top, int right, int bottom)
_video_driver->MakeDirty(left, top, right - left, bottom - top);
}
/*!
/**
* Repaints the rectangle blocks which are marked as 'dirty'.
*
* @see SetDirtyBlocks
@ -1653,7 +1653,7 @@ void DrawDirtyBlocks()
_invalid_rect.bottom = 0;
}
/*!
/**
* This function extends the internal _invalid_rect rectangle as it
* now contains the rectangle defined by the given parameters. Note
* the point (0,0) is top left.
@ -1705,10 +1705,11 @@ void SetDirtyBlocks(int left, int top, int right, int bottom)
} while (--height != 0);
}
/*!
/**
* This function mark the whole screen as dirty. This results in repainting
* the whole screen. Use this with care as this function will break the
* idea about marking only parts of the screen as 'dirty'.
* @ingroup dirty
*/
void MarkWholeScreenDirty()
{

17
src/gfx_func.h
View File

@ -128,25 +128,8 @@ int GetStringHeight(StringID str, int maxw);
Dimension GetStringMultiLineBoundingBox(StringID str, const Dimension &suggestion);
void LoadStringWidthTable();
/**
* Let the dirty blocks repainting by the video driver.
*
* @ingroup dirty
*/
void DrawDirtyBlocks();
/**
* Set a new dirty block.
*
* @ingroup dirty
*/
void SetDirtyBlocks(int left, int top, int right, int bottom);
/**
* Marks the whole screen as dirty.
*
* @ingroup dirty
*/
void MarkWholeScreenDirty();
void GfxInitPalettes();

8
src/group.h
View File

@ -67,14 +67,6 @@ static inline uint GetGroupArraySize()
return num;
}
/**
* Get the number of engines with EngineID id_e in the group with GroupID
* id_g
* @param company The company the group belongs to
* @param id_g The GroupID of the group used
* @param id_e The EngineID of the engine to count
* @return The number of engines with EngineID id_e in the group
*/
uint GetGroupNumEngines(CompanyID company, GroupID id_g, EngineID id_e);
static inline void IncreaseGroupNumVehicle(GroupID id_g)

8
src/group_cmd.cpp
View File

@ -409,6 +409,14 @@ void UpdateTrainGroupID(Train *v)
SetWindowDirty(WC_REPLACE_VEHICLE, VEH_TRAIN);
}
/**
* Get the number of engines with EngineID id_e in the group with GroupID
* id_g
* @param company The company the group belongs to
* @param id_g The GroupID of the group used
* @param id_e The EngineID of the engine to count
* @return The number of engines with EngineID id_e in the group
*/
uint GetGroupNumEngines(CompanyID company, GroupID id_g, EngineID id_e)
{
if (Group::IsValidID(id_g)) return Group::Get(id_g)->num_engines[id_e];

17
src/heightmap.cpp
View File

@ -430,11 +430,24 @@ static bool ReadHeightMap(char *filename, uint *x, uint *y, byte **map)
}
}
/**
* Get the dimensions of a heightmap.
* @param filename to query
* @param x dimension x
* @param y dimension y
* @return Returns false if loading of the image failed.
*/
bool GetHeightmapDimensions(char *filename, uint *x, uint *y)
{
return ReadHeightMap(filename, x, y, NULL);
}
/**
* Load a heightmap from file and change the map in his current dimensions
* to a landscape representing the heightmap.
* It converts pixels to height. The brighter, the higher.
* @param filename of the heighmap file to be imported
*/
void LoadHeightmap(char *filename)
{
uint x, y;
@ -452,6 +465,10 @@ void LoadHeightmap(char *filename)
MarkWholeScreenDirty();
}
/**
* Make an empty world where all tiles are of height 'tile_height'.
* @param tile_height of the desired new empty world
*/
void FlatEmptyWorld(byte tile_height)
{
int edge_distance = _settings_game.construction.freeform_edges ? 0 : 2;

26
src/heightmap.h
View File

@ -12,7 +12,7 @@
#ifndef HEIGHTMAP_H
#define HEIGHTMAP_H
/*
/**
* Order of these enums has to be the same as in lang/english.txt
* Otherwise you will get inconsistent behaviour.
*/
@ -21,33 +21,9 @@ enum HeightmapRotation {
HM_CLOCKWISE, ///< Rotate the map clockwise 45 degrees
};
/**
* Get the dimensions of a heightmap.
* @param filename to query
* @param x dimension x
* @param y dimension y
* @return Returns false if loading of the image failed.
*/
bool GetHeightmapDimensions(char *filename, uint *x, uint *y);
/**
* Load a heightmap from file and change the map in his current dimensions
* to a landscape representing the heightmap.
* It converts pixels to height. The brighter, the higher.
* @param filename of the heighmap file to be imported
*/
void LoadHeightmap(char *filename);
/**
* Make an empty world where all tiles are of height 'tile_height'.
* @param tile_height of the desired new empty world
*/
void FlatEmptyWorld(byte tile_height);
/**
* This function takes care of the fact that land in OpenTTD can never differ
* more than 1 in height
*/
void FixSlopes();
#endif /* HEIGHTMAP_H */

4
src/house.h
View File

@ -121,10 +121,6 @@ struct HouseSpec {
byte processing_time; ///< Periodic refresh multiplier
byte minimum_life; ///< The minimum number of years this house will survive before the town rebuilds it
/**
* Get the cost for removing this house
* @return the cost (inflation corrected etc)
*/
Money GetRemovalCost() const;
static FORCEINLINE HouseSpec *Get(size_t house_id)

18
src/industry_cmd.cpp
View File

@ -2644,6 +2644,10 @@ void InitializeIndustries()
_industry_builder.Reset();
}
/**
* Is an industry with the spec a raw industry?
* @return true if it should be handled as a raw industry
*/
bool IndustrySpec::IsRawIndustry() const
{
/* Lumber mills are extractive/organic, but can always be built like a non-raw industry */
@ -2651,6 +2655,10 @@ bool IndustrySpec::IsRawIndustry() const
(this->behaviour & INDUSTRYBEH_CUT_TREES) == 0;
}
/**
* Get the cost for constructing this industry
* @return the cost (inflation corrected etc)
*/
Money IndustrySpec::GetConstructionCost() const
{
/* Building raw industries like secondary uses different price base */
@ -2658,11 +2666,21 @@ Money IndustrySpec::GetConstructionCost() const
PR_BUILD_INDUSTRY_RAW : PR_BUILD_INDUSTRY] * this->cost_multiplier) >> 8;
}
/**
* Get the cost for removing this industry
* Take note that the cost will always be zero for non-grf industries.
* Only if the grf author did specified a cost will it be applicable.
* @return the cost (inflation corrected etc)
*/
Money IndustrySpec::GetRemovalCost() const
{
return (_price[PR_CLEAR_INDUSTRY] * this->removal_cost_multiplier) >> 8;
}
/**
* Determines whether this industrytype uses smooth economy or whether it uses standard/newgrf production changes.
* @return true if smooth economy is used.
*/
bool IndustrySpec::UsesSmoothEconomy() const
{
return _settings_game.economy.smooth_economy &&

21
src/industrytype.h
View File

@ -134,30 +134,9 @@ struct IndustrySpec {
bool enabled; ///< entity still available (by default true).newgrf can disable it, though
GRFFileProps grf_prop; ///< properties related to the grf file
/**
* Is an industry with the spec a raw industry?
* @return true if it should be handled as a raw industry
*/
bool IsRawIndustry() const;
/**
* Get the cost for constructing this industry
* @return the cost (inflation corrected etc)
*/
Money GetConstructionCost() const;
/**
* Get the cost for removing this industry
* Take note that the cost will always be zero for non-grf industries.
* Only if the grf author did specified a cost will it be applicable.
* @return the cost (inflation corrected etc)
*/
Money GetRemovalCost() const;
/**
* Determines whether this industrytype uses smooth economy or whether it uses standard/newgrf production changes.
* @return true if smooth economy is used.
*/
bool UsesSmoothEconomy() const;
};

55
src/ini.cpp
View File

@ -26,6 +26,12 @@
# include <shellapi.h>
#endif
/**
* Construct a new in-memory item of an Ini file.
* @param parent the group we belong to
* @param name the name of the item
* @param len the length of the name of the item
*/
IniItem::IniItem(IniGroup *parent, const char *name, size_t len) : next(NULL), value(NULL), comment(NULL)
{
if (len == 0) len = strlen(name);
@ -35,6 +41,7 @@ IniItem::IniItem(IniGroup *parent, const char *name, size_t len) : next(NULL), v
parent->last_item = &this->next;
}
/** Free everything we loaded. */
IniItem::~IniItem()
{
free(this->name);
@ -44,12 +51,22 @@ IniItem::~IniItem()
delete this->next;
}
/**
* Replace the current value with another value.
* @param value the value to replace with.
*/
void IniItem::SetValue(const char *value)
{
free(this->value);
this->value = strdup(value);
}
/**
* Construct a new in-memory group of an Ini file.
* @param parent the file we belong to
* @param name the name of the group
* @param len the length of the name of the group
*/
IniGroup::IniGroup(IniFile *parent, const char *name, size_t len) : next(NULL), type(IGT_VARIABLES), item(NULL), comment(NULL)
{
if (len == 0) len = strlen(name);
@ -69,6 +86,7 @@ IniGroup::IniGroup(IniFile *parent, const char *name, size_t len) : next(NULL),
}
}
/** Free everything we loaded. */
IniGroup::~IniGroup()
{
free(this->name);
@ -78,6 +96,13 @@ IniGroup::~IniGroup()
delete this->next;
}
/**
* Get the item with the given name, and if it doesn't exist
* and create is true it creates a new item.
* @param name name of the item to find.
* @param create whether to create an item when not found or not.
* @return the requested item or NULL if not found.
*/
IniItem *IniGroup::GetItem(const char *name, bool create)
{
for (IniItem *item = this->item; item != NULL; item = item->next) {
@ -90,6 +115,9 @@ IniItem *IniGroup::GetItem(const char *name, bool create)
return new IniItem(this, name, strlen(name));
}
/**
* Clear all items in the group
*/
void IniGroup::Clear()
{
delete this->item;
@ -97,17 +125,30 @@ void IniGroup::Clear()
this->last_item = &this->item;
}
/**
* Construct a new in-memory Ini file representation.
* @param list_group_names A NULL terminated list with groups that should be
* loaded as lists instead of variables.
*/
IniFile::IniFile(const char * const *list_group_names) : group(NULL), comment(NULL), list_group_names(list_group_names)
{
this->last_group = &this->group;
}
/** Free everything we loaded. */
IniFile::~IniFile()
{
free(this->comment);
delete this->group;
}
/**
* Get the group with the given name, and if it doesn't exist
* create a new group.
* @param name name of the group to find.
* @param len the maximum length of said name.
* @return the requested group.
*/
IniGroup *IniFile::GetGroup(const char *name, size_t len)
{
if (len == 0) len = strlen(name);
@ -125,6 +166,10 @@ IniGroup *IniFile::GetGroup(const char *name, size_t len)
return group;
}
/**
* Remove the group with the given name.
* @param name name of the group to remove.
*/
void IniFile::RemoveGroup(const char *name)
{
size_t len = strlen(name);
@ -152,6 +197,11 @@ void IniFile::RemoveGroup(const char *name)
delete group;
}
/**
* Load the Ini file's data from the disk.
* @param filename the file to load.
* @pre nothing has been loaded yet.
*/
void IniFile::LoadFromDisk(const char *filename)
{
assert(this->last_group == &this->group);
@ -268,6 +318,11 @@ void IniFile::LoadFromDisk(const char *filename)
fclose(in);
}
/**
* Save the Ini file's data to the disk.
* @param filename the file to save to.
* @return true if saving succeeded.
*/
bool IniFile::SaveToDisk(const char *filename)
{
/*

61
src/ini_type.h
View File

@ -25,21 +25,9 @@ struct IniItem {
char *value; ///< The value of this item
char *comment; ///< The comment associated with this item
/**
* Construct a new in-memory item of an Ini file.
* @param parent the group we belong to
* @param name the name of the item
* @param len the length of the name of the item
*/
IniItem(struct IniGroup *parent, const char *name, size_t len = 0);
/** Free everything we loaded. */
~IniItem();
/**
* Replace the current value with another value.
* @param value the value to replace with.
*/
void SetValue(const char *value);
};
@ -52,29 +40,10 @@ struct IniGroup {
char *name; ///< name of group
char *comment; ///< comment for group
/**
* Construct a new in-memory group of an Ini file.
* @param parent the file we belong to
* @param name the name of the group
* @param len the length of the name of the group
*/
IniGroup(struct IniFile *parent, const char *name, size_t len = 0);
/** Free everything we loaded. */
~IniGroup();
/**
* Get the item with the given name, and if it doesn't exist
* and create is true it creates a new item.
* @param name name of the item to find.
* @param create whether to create an item when not found or not.
* @return the requested item or NULL if not found.
*/
IniItem *GetItem(const char *name, bool create);
/**
* Clear all items in the group
*/
void Clear();
};
@ -85,43 +54,13 @@ struct IniFile {
char *comment; ///< last comment in file
const char * const *list_group_names; ///< NULL terminated list with group names that are lists
/**
* Construct a new in-memory Ini file representation.
* @param list_group_names A NULL terminated list with groups that should be
* loaded as lists instead of variables.
*/
IniFile(const char * const *list_group_names = NULL);
/** Free everything we loaded. */
~IniFile();
/**
* Get the group with the given name, and if it doesn't exist
* create a new group.
* @param name name of the group to find.
* @param len the maximum length of said name.
* @return the requested group.
*/
IniGroup *GetGroup(const char *name, size_t len = 0);
/**
* Remove the group with the given name.
* @param name name of the group to remove.
*/
void RemoveGroup(const char *name);
/**
* Load the Ini file's data from the disk.
* @param filename the file to load.
* @pre nothing has been loaded yet.
*/
void LoadFromDisk(const char *filename);
/**
* Save the Ini file's data to the disk.
* @param filename the file to save to.
* @return true if saving succeeded.
*/
bool SaveToDisk(const char *filename);
};

4
src/language.h
View File

@ -57,10 +57,6 @@ struct LanguagePackHeader {
char genders[MAX_NUM_GENDERS][CASE_GENDER_LEN]; ///< the genders used by this translation
char cases[MAX_NUM_CASES][CASE_GENDER_LEN]; ///< the cases used by this translation
/**
* Check whether the header is a valid header for OpenTTD.
* @return true iff the header is deemed valid.
*/
bool IsValid() const;
/**

5
src/livery.h
View File

@ -78,11 +78,6 @@ struct Livery {
byte colour2; ///< Second colour, for vehicles with 2CC support.
};
/**
* Reset the livery schemes to the company's primary colour.
* This is used on loading games without livery information and on new company start up.
* @param c Company to reset.
*/
void ResetCompanyLivery(Company *c);
#endif /* LIVERY_H */

22
src/map.cpp
View File

@ -30,7 +30,7 @@ Tile *_m = NULL; ///< Tiles of the map
TileExtended *_me = NULL; ///< Extended Tiles of the map
/*!
/**
* (Re)allocates a map with the given dimension
* @param size_x the width of the map along the NE/SW edge
* @param size_y the 'height' of the map along the SE/NW edge
@ -97,7 +97,7 @@ TileIndex TileAdd(TileIndex tile, TileIndexDiff add,
}
#endif
/*!
/**
* This function checks if we add addx/addy to tile, if we
* do wrap around the edges. For example, tile = (10,2) and
* addx = +3 and addy = -4. This function will now return
@ -144,7 +144,7 @@ extern const TileIndexDiffC _tileoffs_by_dir[] = {
{ 0, -1} ///< DIR_NW
};
/*!
/**
* Gets the Manhattan distance between the two given tiles.
* The Manhattan distance is the sum of the delta of both the
* X and Y component.
@ -161,7 +161,7 @@ uint DistanceManhattan(TileIndex t0, TileIndex t1)
}
/*!
/**
* Gets the 'Square' distance between the two given tiles.
* The 'Square' distance is the square of the shortest (straight line)
* distance between the two tiles.
@ -178,7 +178,7 @@ uint DistanceSquare(TileIndex t0, TileIndex t1)
}
/*!
/**
* Gets the biggest distance component (x or y) between the two given tiles.
* Also known as L-Infinity-Norm.
* @param t0 the start tile
@ -193,7 +193,7 @@ uint DistanceMax(TileIndex t0, TileIndex t1)
}
/*!
/**
* Gets the biggest distance component (x or y) between the two given tiles
* plus the Manhattan distance, i.e. two times the biggest distance component
* and once the smallest component.
@ -208,7 +208,7 @@ uint DistanceMaxPlusManhattan(TileIndex t0, TileIndex t1)
return dx > dy ? 2 * dx + dy : 2 * dy + dx;
}
/*!
/**
* Param the minimum distance to an edge
* @param tile the tile to get the distance from
* @return the distance from the edge in tiles
@ -224,7 +224,7 @@ uint DistanceFromEdge(TileIndex tile)
return min(minl, minh);
}
/*!
/**
* Gets the distance to the edge of the map in given direction.
* @param tile the tile to get the distance from
* @param diagdir the direction of interest
@ -241,7 +241,7 @@ uint DistanceFromEdgeDir(TileIndex tile, DiagDirection dir)
}
}
/*!
/**
* Function performing a search around a center tile and going outward, thus in circle.
* Although it really is a square search...
* Every tile will be tested by means of the callback function proc,
@ -273,7 +273,7 @@ bool CircularTileSearch(TileIndex *tile, uint size, TestTileOnSearchProc proc, v
}
}
/*!
/**
* Generalized circular search allowing for rectangles and a hole.
* Function performing a search around a center rectangle and going outward.
* The center rectangle is left out from the search. To do a rectangular search
@ -330,7 +330,7 @@ bool CircularTileSearch(TileIndex *tile, uint radius, uint w, uint h, TestTileOn
return false;
}
/*!
/**
* Finds the distance for the closest tile with water/land given a tile
* @param tile the tile to find the distance too
* @param water whether to find water or land

16
src/map_func.h
View File

@ -43,9 +43,6 @@ extern Tile *_m;
*/
extern TileExtended *_me;
/**
* Allocate a new map with the given size.
*/
void AllocateMap(uint size_x, uint size_y);
/**
@ -256,9 +253,6 @@ static inline TileIndexDiff ToTileIndexDiff(TileIndexDiffC tidc)
*/
#define TILE_ADDXY(tile, x, y) TILE_ADD(tile, TileDiffXY(x, y))
/**
* Adds an offset to a tile and check if we are still on the map.
*/
TileIndex TileAddWrap(TileIndex tile, int addx, int addy);
/**
@ -403,14 +397,7 @@ static inline DiagDirection DiagdirBetweenTiles(TileIndex tile_from, TileIndex t
*/
typedef bool TestTileOnSearchProc(TileIndex tile, void *user_data);
/**
* Searches for some cirumstances of a tile around a given tile with a helper function.
*/
bool CircularTileSearch(TileIndex *tile, uint size, TestTileOnSearchProc proc, void *user_data);
/**
* Searches for some cirumstances of a tile around a given rectangle with a helper function.
*/
bool CircularTileSearch(TileIndex *tile, uint radius, uint w, uint h, TestTileOnSearchProc proc, void *user_data);
/**
@ -431,9 +418,6 @@ static inline TileIndex RandomTileSeed(uint32 r)
*/
#define RandomTile() RandomTileSeed(Random())
/**
* Finds the distance for the closest tile with water/land given a tile
*/
uint GetClosestWaterDistance(TileIndex tile, bool water);
#endif /* MAP_FUNC_H */

4
src/strings.cpp
View File

@ -1383,6 +1383,10 @@ extern void SortNetworkLanguages();
static inline void SortNetworkLanguages() {}
#endif /* ENABLE_NETWORK */
/**
* Check whether the header is a valid header for OpenTTD.
* @return true iff the header is deemed valid.
*/
bool LanguagePackHeader::IsValid() const
{
return this->ident == TO_LE32(LanguagePackHeader::IDENT) &&

4
src/town_cmd.cpp
View File

@ -157,6 +157,10 @@ void Town::InitializeLayout(TownLayout layout)
return Town::Get(index);
}
/**
* Get the cost for removing this house
* @return the cost (inflation corrected etc)
*/
Money HouseSpec::GetRemovalCost() const
{
return (_price[PR_CLEAR_HOUSE] * this->removal_cost) >> 8;

5
src/viewport.cpp
View File

@ -1638,6 +1638,11 @@ void MarkAllViewportsDirty(int left, int top, int right, int bottom)
}
}
/**
* Mark a tile given by its index dirty for repaint.
* @param tile The tile to mark dirty.
* @ingroup dirty
*/
void MarkTileDirtyByTile(TileIndex tile)
{
Point pt = RemapCoords(TileX(tile) * TILE_SIZE, TileY(tile) * TILE_SIZE, GetTileZ(tile));