diff options
34 files changed, 155 insertions, 19 deletions
diff --git a/src/core/endian_type.hpp b/src/core/endian_type.hpp index ad0b814c6..dbb7faec6 100644 --- a/src/core/endian_type.hpp +++ b/src/core/endian_type.hpp @@ -13,12 +13,16 @@ #define ENDIAN_TYPE_HPP #if defined(ARM) || defined(__arm__) || defined(__alpha__) + /** The architecture requires aligned access. */ #define OTTD_ALIGNMENT 1 #else + /** The architecture does not require aligned access. */ #define OTTD_ALIGNMENT 0 #endif +/** Little endian builds use this for TTD_ENDIAN. */ #define TTD_LITTLE_ENDIAN 0 +/** Big endian builds use this for TTD_ENDIAN. */ #define TTD_BIG_ENDIAN 1 /* Windows has always LITTLE_ENDIAN */ diff --git a/src/core/pool_func.hpp b/src/core/pool_func.hpp index 0d9c23165..8f53c66f9 100644 --- a/src/core/pool_func.hpp +++ b/src/core/pool_func.hpp @@ -16,6 +16,10 @@ #include "mem_func.hpp" #include "pool_type.hpp" +/** + * Helper for defining the method's signature. + * @param type The return type of the method. + */ #define DEFINE_POOL_METHOD(type) \ template <class Titem, typename Tindex, size_t Tgrowth_step, size_t Tmax_size, PoolType Tpool_type, bool Tcache, bool Tzero> \ type Pool<Titem, Tindex, Tgrowth_step, Tmax_size, Tpool_type, Tcache, Tzero> diff --git a/src/core/smallvec_type.hpp b/src/core/smallvec_type.hpp index 8116ca2ea..00fb7c5a0 100644 --- a/src/core/smallvec_type.hpp +++ b/src/core/smallvec_type.hpp @@ -35,12 +35,20 @@ protected: public: SmallVector() : data(NULL), items(0), capacity(0) { } + /** + * Copy constructor. + * @param other The other vector to copy. + */ template <uint X> SmallVector(const SmallVector<T, X> &other) : data(NULL), items(0), capacity(0) { MemCpyT<T>(this->Append(other.Length()), other.Begin(), other.Length()); } + /** + * Assignment. + * @param other The new vector that. + */ template <uint X> SmallVector &operator=(const SmallVector<T, X> &other) { @@ -318,6 +326,6 @@ public: } }; -typedef AutoFreeSmallVector<char*, 4> StringList; +typedef AutoFreeSmallVector<char*, 4> StringList; ///< Type for a list of strings. #endif /* SMALLVEC_TYPE_HPP */ diff --git a/src/core/string_compare_type.hpp b/src/core/string_compare_type.hpp index 2bc018feb..77180747b 100644 --- a/src/core/string_compare_type.hpp +++ b/src/core/string_compare_type.hpp @@ -12,7 +12,14 @@ #ifndef STRING_COMPARE_TYPE_HPP #define STRING_COMPARE_TYPE_HPP +/** Comparator for strings. */ struct StringCompare { + /** + * Compare two strings. + * @param a The first string. + * @param b The second string. + * @return True is the first string is deemed "lower" than the second string. + */ bool operator () (const char *a, const char *b) const { return strcmp(a, b) < 0; diff --git a/src/currency.cpp b/src/currency.cpp index f66d18778..d0d474c41 100644 --- a/src/currency.cpp +++ b/src/currency.cpp @@ -22,6 +22,7 @@ * | separator | postfix | * | | Euro year | | | name * | | | | | | | */ +/** The original currency specifications. */ static const CurrencySpec origin_currency_specs[NUM_CURRENCY] = { { 1, "", CF_NOEURO, "\xC2\xA3", "", 0, STR_GAME_OPTIONS_CURRENCY_GBP }, ///< british pounds { 2, "", CF_NOEURO, "$", "", 0, STR_GAME_OPTIONS_CURRENCY_USD }, ///< us dollars @@ -54,7 +55,7 @@ static const CurrencySpec origin_currency_specs[NUM_CURRENCY] = { { 1, "", CF_NOEURO, "", "", 2, STR_GAME_OPTIONS_CURRENCY_CUSTOM }, ///< custom currency }; -/* Array of currencies used by the system */ +/** Array of currencies used by the system */ CurrencySpec _currency_specs[NUM_CURRENCY]; /** diff --git a/src/date.cpp b/src/date.cpp index 9f91a2280..52827d117 100644 --- a/src/date.cpp +++ b/src/date.cpp @@ -23,7 +23,7 @@ Year _cur_year; ///< Current year, starting at 0 Month _cur_month; ///< Current month (0..11) Date _date; ///< Current date in days (day counter) -DateFract _date_fract; +DateFract _date_fract; ///< Fractional part of the day. uint16 _tick_counter; ///< Ever incrementing (and sometimes wrapping) tick counter for setting off various events /** diff --git a/src/date_func.h b/src/date_func.h index 38e310a87..6bbde5955 100644 --- a/src/date_func.h +++ b/src/date_func.h @@ -24,6 +24,11 @@ void SetDate(Date date, DateFract fract); void ConvertDateToYMD(Date date, YearMonthDay *ymd); Date ConvertYMDToDate(Year year, Month month, Day day); +/** + * Checks whether the given year is a leap year or not. + * @param yr The year to check. + * @return True if \c yr is a leap year, otherwise false. + */ static inline bool IsLeapYear(Year yr) { return yr % 4 == 0 && (yr % 100 != 0 || yr % 400 == 0); diff --git a/src/date_gui.cpp b/src/date_gui.cpp index 85e9fcb7a..fa9f17507 100644 --- a/src/date_gui.cpp +++ b/src/date_gui.cpp @@ -181,6 +181,7 @@ struct SetDateWindow : Window { } }; +/** Widgets for the date setting window. */ static const NWidgetPart _nested_set_date_widgets[] = { NWidget(NWID_HORIZONTAL), NWidget(WWT_CLOSEBOX, COLOUR_BROWN), @@ -202,6 +203,7 @@ static const NWidgetPart _nested_set_date_widgets[] = { EndContainer() }; +/** Description of the date setting window. */ static const WindowDesc _set_date_desc( WDP_CENTER, 0, 0, WC_SET_DATE, WC_NONE, diff --git a/src/depend/depend.cpp b/src/depend/depend.cpp index a7c4285e3..c224efdaf 100644 --- a/src/depend/depend.cpp +++ b/src/depend/depend.cpp @@ -31,6 +31,7 @@ #include <stack> #ifndef PATH_MAX +/** The maximum length of paths, if we don't know it. */ # define PATH_MAX 260 #endif diff --git a/src/depot.cpp b/src/depot.cpp index e09179b69..4fb69c8e3 100644 --- a/src/depot.cpp +++ b/src/depot.cpp @@ -18,6 +18,7 @@ #include "vehicle_gui.h" #include "vehiclelist.h" +/** All our depots tucked away in a pool. */ DepotPool _depot_pool("Depot"); INSTANTIATE_POOL_METHODS(Depot) diff --git a/src/depot_cmd.cpp b/src/depot_cmd.cpp index bfc77e3ef..da4b0bfb1 100644 --- a/src/depot_cmd.cpp +++ b/src/depot_cmd.cpp @@ -21,7 +21,11 @@ #include "table/strings.h" - +/** + * Check whether the given name is globally unique amongst depots. + * @param name The name to check. + * @return True if there is no depot with the given name. + */ static bool IsUniqueDepotName(const char *name) { const Depot *d; diff --git a/src/depot_type.h b/src/depot_type.h index c5cbb1ab1..d6374bed5 100644 --- a/src/depot_type.h +++ b/src/depot_type.h @@ -12,7 +12,7 @@ #ifndef DEPOT_TYPE_H #define DEPOT_TYPE_H -typedef uint16 DepotID; +typedef uint16 DepotID; ///< Type for the unique identifier of depots. struct Depot; static const uint MAX_LENGTH_DEPOT_NAME_CHARS = 32; ///< The maximum length of a depot name in characters including '\0' diff --git a/src/direction_type.h b/src/direction_type.h index 4cc6d1b24..b598d2281 100644 --- a/src/direction_type.h +++ b/src/direction_type.h @@ -42,7 +42,7 @@ DECLARE_POSTFIX_INCREMENT(Direction) /** Define basic enum properties */ template <> struct EnumPropsT<Direction> : MakeEnumPropsT<Direction, byte, DIR_BEGIN, DIR_END, INVALID_DIR, 3> {}; -typedef TinyEnumT<Direction> DirectionByte; // typedefing-enumification of Direction +typedef TinyEnumT<Direction> DirectionByte; ///< typedefing-enumification of Direction /** @@ -92,7 +92,7 @@ DECLARE_POSTFIX_INCREMENT(DiagDirection) /** Define basic enum properties */ template <> struct EnumPropsT<DiagDirection> : MakeEnumPropsT<DiagDirection, byte, DIAGDIR_BEGIN, DIAGDIR_END, INVALID_DIAGDIR, 2> {}; -typedef TinyEnumT<DiagDirection> DiagDirectionByte; // typedefing-enumification of DiagDirection +typedef TinyEnumT<DiagDirection> DiagDirectionByte; ///< typedefing-enumification of DiagDirection /** @@ -130,6 +130,7 @@ enum Axis { AXIS_END, ///< Used for iterations INVALID_AXIS = 0xFF, ///< Flag for an invalid Axis }; +/** Helper information for extract tool. */ template <> struct EnumPropsT<Axis> : MakeEnumPropsT<Axis, byte, AXIS_X, AXIS_END, INVALID_AXIS, 1> {}; #endif /* DIRECTION_TYPE_H */ diff --git a/src/economy_base.h b/src/economy_base.h index edad76ed2..742d01878 100644 --- a/src/economy_base.h +++ b/src/economy_base.h @@ -48,7 +48,17 @@ struct CargoPayment : CargoPaymentPool::PoolItem<&_cargo_payment_pool> { void SetCargo(CargoID ct) { this->ct = ct; } }; +/** + * Iterate over all cargo payments from a given start position. + * @param var The variable used for iterating. + * @param start The start of the iteration. + */ #define FOR_ALL_CARGO_PAYMENTS_FROM(var, start) FOR_ALL_ITEMS_FROM(CargoPayment, cargo_payment_index, var, start) + +/** + * Iterate over all cargo payments. + * @param var The variable used for iterating. + */ #define FOR_ALL_CARGO_PAYMENTS(var) FOR_ALL_CARGO_PAYMENTS_FROM(var, 0) #endif /* ECONOMY_BASE_H */ diff --git a/src/effectvehicle.cpp b/src/effectvehicle.cpp index 1ad8cd297..cfd470d46 100644 --- a/src/effectvehicle.cpp +++ b/src/effectvehicle.cpp @@ -558,6 +558,14 @@ static EffectTickProc * const _effect_tick_procs[] = { }; +/** + * Create an effect vehicle at a particular location. + * @param x The x location on the map. + * @param y The y location on the map. + * @param z The z location on the map. + * @param type The type of effect vehicle. + * @return The effect vehicle. + */ EffectVehicle *CreateEffectVehicle(int x, int y, int z, EffectVehicleType type) { if (!Vehicle::CanAllocateItem()) return NULL; @@ -579,6 +587,14 @@ EffectVehicle *CreateEffectVehicle(int x, int y, int z, EffectVehicleType type) return v; } +/** + * Create an effect vehicle above a particular location. + * @param x The x location on the map. + * @param y The y location on the map. + * @param z The offset from the ground. + * @param type The type of effect vehicle. + * @return The effect vehicle. + */ EffectVehicle *CreateEffectVehicleAbove(int x, int y, int z, EffectVehicleType type) { int safe_x = Clamp(x, 0, MapMaxX() * TILE_SIZE); @@ -586,6 +602,15 @@ EffectVehicle *CreateEffectVehicleAbove(int x, int y, int z, EffectVehicleType t return CreateEffectVehicle(x, y, GetSlopeZ(safe_x, safe_y) + z, type); } +/** + * Create an effect vehicle above a particular vehicle. + * @param v The vehicle to base the position on. + * @param x The x offset to the vehicle. + * @param y The y offset to the vehicle. + * @param z The z offset to the vehicle. + * @param type The type of effect vehicle. + * @return The effect vehicle. + */ EffectVehicle *CreateEffectVehicleRel(const Vehicle *v, int x, int y, int z, EffectVehicleType type) { return CreateEffectVehicle(v->x_pos + x, v->y_pos + y, v->z_pos + z, type); diff --git a/src/elrail.cpp b/src/elrail.cpp index 701d17a26..8188fa15e 100644 --- a/src/elrail.cpp +++ b/src/elrail.cpp @@ -67,6 +67,11 @@ #include "table/elrail_data.h" +/** + * Get the tile location group of a tile. + * @param t The tile to get the tile location group of. + * @return The tile location group. + */ static inline TLG GetTLG(TileIndex t) { return (TLG)((HasBit(TileX(t), 0) << 1) + HasBit(TileY(t), 0)); diff --git a/src/engine.cpp b/src/engine.cpp index f55b46c0f..a968d5263 100644 --- a/src/engine.cpp +++ b/src/engine.cpp @@ -614,6 +614,11 @@ void SetYearEngineAgingStops() } } +/** + * Start/initialise one engine. + * @param e The engine to initialise. + * @param aging_date The date used for age calculations. + */ void StartupOneEngine(Engine *e, Date aging_date) { const EngineInfo *ei = &e->info; @@ -654,6 +659,7 @@ void StartupOneEngine(Engine *e, Date aging_date) } } +/** Start/initialise all our engines. */ void StartupEngines() { Engine *e; diff --git a/src/engine_gui.cpp b/src/engine_gui.cpp index 3fd30efd7..1c89d3a36 100644 --- a/src/engine_gui.cpp +++ b/src/engine_gui.cpp @@ -128,6 +128,11 @@ void ShowEnginePreviewWindow(EngineID engine) AllocateWindowDescFront<EnginePreviewWindow>(&_engine_preview_desc, engine); } +/** + * Get the capacity of an engine with articulated parts. + * @param engine The engine to get the capacity of. + * @return The capacity. + */ uint GetTotalCapacityOfArticulatedParts(EngineID engine) { uint total = 0; diff --git a/src/gamelog.cpp b/src/gamelog.cpp index 7ad4b297b..4cda9de14 100644 --- a/src/gamelog.cpp +++ b/src/gamelog.cpp @@ -326,6 +326,7 @@ static void GamelogPrintConsoleProc(const char *s) IConsolePrint(CC_WARNING, s); } +/** Print the gamelog data to the console. */ void GamelogPrintConsole() { GamelogPrint(&GamelogPrintConsoleProc); diff --git a/src/gamelog.h b/src/gamelog.h index 3bb698697..0fa54e9c2 100644 --- a/src/gamelog.h +++ b/src/gamelog.h @@ -14,6 +14,7 @@ #include "newgrf_config.h" +/** The actions we log. */ enum GamelogActionType { GLAT_START, ///< Game created GLAT_LOAD, ///< Game loaded @@ -31,6 +32,10 @@ void GamelogStopAction(); void GamelogReset(); +/** + * Callback for printing text. + * @param s The string to print. + */ typedef void GamelogPrintProc(const char *s); void GamelogPrint(GamelogPrintProc *proc); // needed for WIN32 / WINCE crash.log diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp index f1a58679b..f51d1fdfe 100644 --- a/src/genworld_gui.cpp +++ b/src/genworld_gui.cpp @@ -875,21 +875,28 @@ static void _ShowGenerateLandscape(GenenerateLandscapeWindowMode mode) SetWindowDirty(WC_GENERATE_LANDSCAPE, mode); } +/** Start with a normal game. */ void ShowGenerateLandscape() { _ShowGenerateLandscape(GLWM_GENERATE); } +/** Start with loading a heightmap. */ void ShowHeightmapLoad() { _ShowGenerateLandscape(GLWM_HEIGHTMAP); } +/** Start with a scenario editor. */ void StartScenarioEditor() { StartGeneratingLandscape(GLWM_SCENARIO); } +/** + * Start a normal game without the GUI. + * @param seed The seed of the new game. + */ void StartNewGameWithoutGUI(uint seed) { /* GenerateWorld takes care of the possible GENERATE_NEW_SEED value in 'seed' */ @@ -1155,6 +1162,7 @@ static const WindowDesc _create_scenario_desc( _nested_create_scenario_widgets, lengthof(_nested_create_scenario_widgets) ); +/** Show the window to create a scenario. */ void ShowCreateScenario() { DeleteWindowByClass(WC_GENERATE_LANDSCAPE); diff --git a/src/gfxinit.cpp b/src/gfxinit.cpp index ae4eec92e..4270a102e 100644 --- a/src/gfxinit.cpp +++ b/src/gfxinit.cpp @@ -135,7 +135,7 @@ void CheckExternalFiles() if (add_pos != error_msg) ShowInfoF("%s", error_msg); } - +/** Actually load the sprite tables. */ static void LoadSpriteTables() { memset(_palette_remap_grf, 0, sizeof(_palette_remap_grf)); @@ -199,6 +199,7 @@ static void LoadSpriteTables() } +/** Initialise and load all the sprites. */ void GfxLoadSprites() { DEBUG(sprite, 2, "Loading sprite set %d", _settings_game.game_creation.landscape); diff --git a/src/group_gui.cpp b/src/group_gui.cpp index d745a5ed2..e5762ca26 100644 --- a/src/group_gui.cpp +++ b/src/group_gui.cpp @@ -661,6 +661,11 @@ static const WindowDesc _train_group_desc( _nested_group_widgets, lengthof(_nested_group_widgets) ); +/** + * Show the group window for the given company and vehicle type. + * @param company The company to show the window for. + * @param vehicle_type The type of vehicle to show it for. + */ void ShowCompanyGroup(CompanyID company, VehicleType vehicle_type) { if (!Company::IsValidID(company)) return; diff --git a/src/group_type.h b/src/group_type.h index 7d09ce3ff..ef93e91d9 100644 --- a/src/group_type.h +++ b/src/group_type.h @@ -12,11 +12,11 @@ #ifndef GROUP_TYPE_H #define GROUP_TYPE_H -typedef uint16 GroupID; +typedef uint16 GroupID; ///< Type for all group identifiers. -static const GroupID ALL_GROUP = 0xFFFD; -static const GroupID DEFAULT_GROUP = 0xFFFE; ///< ungrouped vehicles are in this group. -static const GroupID INVALID_GROUP = 0xFFFF; +static const GroupID ALL_GROUP = 0xFFFD; ///< All vehicles are in this group. +static const GroupID DEFAULT_GROUP = 0xFFFE; ///< Ungrouped vehicles are in this group. +static const GroupID INVALID_GROUP = 0xFFFF; ///< Sentinel for invalid groups. static const uint MAX_LENGTH_GROUP_NAME_CHARS = 32; ///< The maximum length of a group name in characters including '\0' diff --git a/src/house_type.h b/src/house_type.h index b59f0a168..9c9c41702 100644 --- a/src/house_type.h +++ b/src/house_type.h @@ -12,8 +12,8 @@ #ifndef HOUSE_TYPE_H #define HOUSE_TYPE_H -typedef uint16 HouseID; -typedef uint16 HouseClassID; +typedef uint16 HouseID; ///< OpenTTD ID of house types. +typedef uint16 HouseClassID; ///< Classes of houses. struct HouseSpec; diff --git a/src/ini.cpp b/src/ini.cpp index ea7639911..8173d3733 100644 --- a/src/ini.cpp +++ b/src/ini.cpp @@ -25,6 +25,10 @@ # include "core/mem_func.hpp" #endif +/** + * Create a new ini file with given group names. + * @param list_group_names A \c NULL terminated list with group names that should be loaded as lists instead of variables. @see IGT_LIST + */ IniFile::IniFile(const char * const *list_group_names) : IniLoadFile(list_group_names) { } diff --git a/src/language.h b/src/language.h index 2f67cd023..6ba731ebf 100644 --- a/src/language.h +++ b/src/language.h @@ -85,6 +85,7 @@ struct LanguagePackHeader { return MAX_NUM_CASES; } }; +/** Make sure the size is right. */ assert_compile(sizeof(LanguagePackHeader) % 4 == 0); /** Metadata about a single language. */ diff --git a/src/livery.h b/src/livery.h index 7ffa4a644..5845ffabb 100644 --- a/src/livery.h +++ b/src/livery.h @@ -59,6 +59,7 @@ enum LiveryScheme { }; DECLARE_POSTFIX_INCREMENT(LiveryScheme) +/** Helper information for extract tool. */ template <> struct EnumPropsT<LiveryScheme> : MakeEnumPropsT<LiveryScheme, byte, LS_BEGIN, LS_END, LS_END, 8> {}; /** List of different livery classes, used only by the livery GUI. */ @@ -71,7 +72,7 @@ enum LiveryClass { LC_END }; - +/** Information about a particular livery. */ struct Livery { bool in_use; ///< Set if this livery should be used instead of the default livery. byte colour1; ///< First colour, for all vehicles. diff --git a/src/map.cpp b/src/map.cpp index fa942b098..2de65ed84 100644 --- a/src/map.cpp +++ b/src/map.cpp @@ -228,7 +228,7 @@ uint DistanceFromEdge(TileIndex tile) /** * 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 + * @param dir the direction of interest * @return the distance from the edge in tiles */ uint DistanceFromEdgeDir(TileIndex tile, DiagDirection dir) diff --git a/src/map_func.h b/src/map_func.h index a2b866483..105090fd8 100644 --- a/src/map_func.h +++ b/src/map_func.h @@ -187,6 +187,12 @@ static inline TileIndexDiff TileDiffXY(int x, int y) return (y * MapSizeX()) + x; } +/** + * Get a tile from the virtual XY-coordinate. + * @param x The virtual x coordinate of the tile. + * @param y The virtual y coordinate of the tile. + * @return The TileIndex calculated by the coordinate. + */ static inline TileIndex TileVirtXY(uint x, uint y) { return (y >> 4 << MapLogX()) + (x >> 4); diff --git a/src/misc/array.hpp b/src/misc/array.hpp index 3434ca21f..5eae3e488 100644 --- a/src/misc/array.hpp +++ b/src/misc/array.hpp @@ -76,6 +76,10 @@ public: return item; } + /** + * Helper for creating a human readable output of this data. + * @param dmp The location to dump to. + */ template <typename D> void Dump(D &dmp) const { dmp.WriteLine("capacity = %d", Tcapacity); diff --git a/src/misc/binaryheap.hpp b/src/misc/binaryheap.hpp index c0aee7f2d..76f93371e 100644 --- a/src/misc/binaryheap.hpp +++ b/src/misc/binaryheap.hpp @@ -14,12 +14,14 @@ #include "../core/alloc_func.hpp" -/* Enable it if you suspect binary heap doesn't work well */ +/** Enable it if you suspect binary heap doesn't work well */ #define BINARYHEAP_CHECK 0 #if BINARYHEAP_CHECK + /** Check for consistency. */ #define CHECK_CONSISTY() this->CheckConsistency() #else + /** Don't check for consistency. */ #define CHECK_CONSISTY() ; #endif @@ -55,6 +57,10 @@ private: T **data; ///< The pointer to the heap item pointers public: + /** + * Create a binary heap. + * @param max_items The limit of the heap + */ explicit CBinaryHeapT(uint max_items) : items(0) , capacity(max_items) diff --git a/src/misc/fixedsizearray.hpp b/src/misc/fixedsizearray.hpp index c9e4ea59a..8b82373fa 100644 --- a/src/misc/fixedsizearray.hpp +++ b/src/misc/fixedsizearray.hpp @@ -31,8 +31,8 @@ protected: }; /* make constants visible from outside */ - static const uint Tsize = sizeof(T); // size of item - static const uint HeaderSize = sizeof(ArrayHeader); // size of header + static const uint Tsize = sizeof(T); ///< size of item + static const uint HeaderSize = sizeof(ArrayHeader); ///< size of header /** * the only member of fixed size array is pointer to the block diff --git a/src/strings.cpp b/src/strings.cpp index 148790425..1be6855c5 100644 --- a/src/strings.cpp +++ b/src/strings.cpp @@ -1476,6 +1476,11 @@ bool LanguagePackHeader::IsValid() const StrValid(this->digit_decimal_separator, lastof(this->digit_decimal_separator)); } +/** + * Read a particular language. + * @param lang The metadata about the language. + * @return Whether the loading went okay or not. + */ bool ReadLanguagePack(const LanguageMetadata *lang) { /* Current language pack */ |