diff --git a/Doxyfile b/Doxyfile index 0fb412a86f..fc05faa234 100644 --- a/Doxyfile +++ b/Doxyfile @@ -195,7 +195,7 @@ EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = -PREDEFINED = ENABLE_NETWORK ENABLE_AI WITH_ZLIB WITH_LZO WITH_PNG WITH_FONTCONFIG WITH_FREETYPE WITH_ICU UNICODE _UNICODE +PREDEFINED = ENABLE_NETWORK ENABLE_AI WITH_ZLIB WITH_LZO WITH_LZMA WITH_SDL WITH_PNG WITH_FONTCONFIG WITH_FREETYPE WITH_ICU UNICODE _UNICODE _GNU_SOURCE EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- diff --git a/src/road_cmd.cpp b/src/road_cmd.cpp index 425d95c2e5..26fc8eb2c0 100644 --- a/src/road_cmd.cpp +++ b/src/road_cmd.cpp @@ -1299,6 +1299,13 @@ static void DrawTile_Road(TileInfo *ti) DrawBridgeMiddle(ti); } +/** + * Draw the road depot sprite. + * @param x The x offset to draw at. + * @param y The y offset to draw at. + * @param dir The direction the depot must be facing. + * @param rt The road type of the depot to draw. + */ void DrawRoadDepotSprite(int x, int y, DiagDirection dir, RoadType rt) { PaletteID palette = COMPANY_SPRITE_COLOUR(_local_company); diff --git a/src/road_gui.cpp b/src/road_gui.cpp index 9637240f33..ef287972a2 100644 --- a/src/road_gui.cpp +++ b/src/road_gui.cpp @@ -833,6 +833,10 @@ static const WindowDesc _build_road_scen_desc( _nested_build_road_scen_widgets, lengthof(_nested_build_road_scen_widgets) ); +/** + * Show the road building toolbar in the scenario editor. + * @return The just opened toolbar. + */ Window *ShowBuildRoadScenToolbar() { _cur_roadtype = ROADTYPE_ROAD; diff --git a/src/road_map.h b/src/road_map.h index 62f125dbb7..bbc7b01e2d 100644 --- a/src/road_map.h +++ b/src/road_map.h @@ -260,6 +260,7 @@ enum DisallowedRoadDirections { DRD_END }; DECLARE_ENUM_AS_BIT_SET(DisallowedRoadDirections) +/** Helper information for extract tool. */ template <> struct EnumPropsT : MakeEnumPropsT {}; /** @@ -311,7 +312,7 @@ static inline Axis GetCrossingRailAxis(TileIndex t) /** * Get the road bits of a level crossing. - * @param t The tile to query. + * @param tile The tile to query. * @return The present road bits. */ static inline RoadBits GetCrossingRoadBits(TileIndex tile) @@ -321,7 +322,7 @@ static inline RoadBits GetCrossingRoadBits(TileIndex tile) /** * Get the rail track of a level crossing. - * @param t The tile to query. + * @param tile The tile to query. * @return The rail track. */ static inline Track GetCrossingRailTrack(TileIndex tile) @@ -331,7 +332,7 @@ static inline Track GetCrossingRailTrack(TileIndex tile) /** * Get the rail track bits of a level crossing. - * @param t The tile to query. + * @param tile The tile to query. * @return The rail track bits. */ static inline TrackBits GetCrossingRailBits(TileIndex tile) diff --git a/src/roadstop.cpp b/src/roadstop.cpp index 74d8aa749e..3b9fc88bd2 100644 --- a/src/roadstop.cpp +++ b/src/roadstop.cpp @@ -16,6 +16,7 @@ #include "station_base.h" #include "vehicle_func.h" +/** The pool of roadstops. */ RoadStopPool _roadstop_pool("RoadStop"); INSTANTIATE_POOL_METHODS(RoadStop) diff --git a/src/saveload/cargopacket_sl.cpp b/src/saveload/cargopacket_sl.cpp index eafe5346b7..e36cede7cd 100644 --- a/src/saveload/cargopacket_sl.cpp +++ b/src/saveload/cargopacket_sl.cpp @@ -15,6 +15,9 @@ #include "saveload.h" +/** + * Savegame conversion for cargopackets. + */ /* static */ void CargoPacket::AfterLoad() { if (IsSavegameVersionBefore(44)) { @@ -101,6 +104,9 @@ const SaveLoad *GetCargoPacketDesc() return _cargopacket_desc; } +/** + * Save the cargo packets. + */ static void Save_CAPA() { CargoPacket *cp; @@ -111,6 +117,9 @@ static void Save_CAPA() } } +/** + * Load the cargo packets. + */ static void Load_CAPA() { int index; @@ -121,6 +130,7 @@ static void Load_CAPA() } } +/** Chunk handlers related to cargo packets. */ extern const ChunkHandler _cargopacket_chunk_handlers[] = { { 'CAPA', Save_CAPA, Load_CAPA, NULL, NULL, CH_ARRAY | CH_LAST}, }; diff --git a/src/saveload/cheat_sl.cpp b/src/saveload/cheat_sl.cpp index 3908e6a718..724c945df6 100644 --- a/src/saveload/cheat_sl.cpp +++ b/src/saveload/cheat_sl.cpp @@ -14,6 +14,9 @@ #include "saveload.h" +/** + * Save the cheat values. + */ static void Save_CHTS() { /* Cannot use lengthof because _cheats is of type Cheats, not Cheat */ @@ -28,6 +31,9 @@ static void Save_CHTS() } } +/** + * Load the cheat values. + */ static void Load_CHTS() { Cheat *cht = (Cheat*)&_cheats; @@ -39,6 +45,7 @@ static void Load_CHTS() } } +/** Chunk handlers related to cheats. */ extern const ChunkHandler _cheat_chunk_handlers[] = { { 'CHTS', Save_CHTS, Load_CHTS, NULL, NULL, CH_RIFF | CH_LAST}, }; diff --git a/src/saveload/signs_sl.cpp b/src/saveload/signs_sl.cpp index 8aeceddc70..4d98fad81c 100644 --- a/src/saveload/signs_sl.cpp +++ b/src/saveload/signs_sl.cpp @@ -14,6 +14,7 @@ #include "saveload.h" +/** Description of a sign within the savegame. */ static const SaveLoad _sign_desc[] = { SLE_CONDVAR(Sign, name, SLE_NAME, 0, 83), SLE_CONDSTR(Sign, name, SLE_STR, 0, 84, SL_MAX_VERSION), @@ -56,6 +57,7 @@ static void Load_SIGN() } } +/** Chunk handlers related to signs. */ extern const ChunkHandler _sign_chunk_handlers[] = { { 'SIGN', Save_SIGN, Load_SIGN, NULL, NULL, CH_ARRAY | CH_LAST}, }; diff --git a/src/saveload/strings_sl.cpp b/src/saveload/strings_sl.cpp index beb39e965d..07a8ddd9fa 100644 --- a/src/saveload/strings_sl.cpp +++ b/src/saveload/strings_sl.cpp @@ -115,6 +115,9 @@ void InitializeOldNames() _old_name_array = CallocT(512 * 32); // 200 * 24 would be enough for TTO savegames } +/** + * Load the NAME chunk. + */ static void Load_NAME() { int index; @@ -124,6 +127,7 @@ static void Load_NAME() } } +/** Chunk handlers related to strings. */ extern const ChunkHandler _name_chunk_handlers[] = { { 'NAME', NULL, Load_NAME, NULL, NULL, CH_ARRAY | CH_LAST}, }; diff --git a/src/script/script_scanner.hpp b/src/script/script_scanner.hpp index e8f5efb775..415b7f6db7 100644 --- a/src/script/script_scanner.hpp +++ b/src/script/script_scanner.hpp @@ -14,6 +14,7 @@ #include "../fileio_type.h" +/** Scanner to help finding scripts. */ class ScriptScanner { public: ScriptScanner(); @@ -43,8 +44,8 @@ private: void ScanDir(const char *dirname, const char *info_file_name); protected: - class Squirrel *engine; - char main_script[1024]; + class Squirrel *engine; ///< The engine we're scanning with. + char main_script[1024]; ///< The name of the current main script. }; #endif /* SCRIPT_SCANNER_HPP */ diff --git a/src/script/squirrel_helper_type.hpp b/src/script/squirrel_helper_type.hpp index adf88b0e89..946a59547a 100644 --- a/src/script/squirrel_helper_type.hpp +++ b/src/script/squirrel_helper_type.hpp @@ -12,9 +12,10 @@ #ifndef SQUIRREL_HELPER_TYPE_HPP #define SQUIRREL_HELPER_TYPE_HPP +/** Definition of a simple array. */ struct Array { - int32 size; - int32 array[]; + int32 size; ///< The size of the array. + int32 array[]; ///< The data of the array. }; #endif /* SQUIRREL_HELPER_TYPE_HPP */ diff --git a/src/sdl.cpp b/src/sdl.cpp index 949766772a..91d52d917a 100644 --- a/src/sdl.cpp +++ b/src/sdl.cpp @@ -16,6 +16,7 @@ #include "sdl.h" #include +/** Number of users of the SDL library. */ static int _sdl_usage; #ifdef DYNAMICALLY_LOADED_SDL @@ -78,7 +79,10 @@ static const char *LoadSdlDLL() #endif /* DYNAMICALLY_LOADED_SDL */ - +/** + * Open the SDL library. + * @param x The subsystem to load. + */ const char *SdlOpen(uint32 x) { #ifdef DYNAMICALLY_LOADED_SDL @@ -96,6 +100,10 @@ const char *SdlOpen(uint32 x) return NULL; } +/** + * Close the SDL library. + * @param x The subsystem to close. + */ void SdlClose(uint32 x) { if (x != 0) { diff --git a/src/settingsgen/settingsgen.cpp b/src/settingsgen/settingsgen.cpp index faedc3df04..ad602e360b 100644 --- a/src/settingsgen/settingsgen.cpp +++ b/src/settingsgen/settingsgen.cpp @@ -156,13 +156,18 @@ private: return num_blocks > 0 && this->output_buffer[num_blocks - 1].HasRoom(); } - typedef SmallVector OutputBufferVector; + typedef SmallVector OutputBufferVector; ///< Vector type for output buffers. OutputBufferVector output_buffer; ///< Vector of blocks containing the stored output. }; /** Derived class for loading INI files without going through Fio stuff. */ struct SettingsIniFile : IniLoadFile { + /** + * Construct a new ini loader. + * @param list_group_names A \c NULL terminated list with group names that should be loaded as lists instead of variables. @see IGT_LIST + * @param seq_group_names A \c NULL terminated list with group names that should be loaded as lists of names. @see IGT_SEQUENCE + */ SettingsIniFile(const char * const *list_group_names = NULL, const char * const *seq_group_names = NULL) : IniLoadFile(list_group_names, seq_group_names) { diff --git a/src/ship.h b/src/ship.h index 9dc3a78a8d..3a7e21d587 100644 --- a/src/ship.h +++ b/src/ship.h @@ -20,7 +20,7 @@ void GetShipSpriteSize(EngineID engine, uint &width, uint &height); * All ships have this type. */ struct Ship: public SpecializedVehicle { - TrackBitsByte state; + TrackBitsByte state; ///< The "track" the ship is following. /** We don't want GCC to zero our struct! It already is zeroed and has an index! */ Ship() : SpecializedVehicleBase() {} @@ -45,6 +45,10 @@ struct Ship: public SpecializedVehicle { void UpdateCache(); }; +/** + * Iterate over all ships. + * @param var The variable used for iteration. + */ #define FOR_ALL_SHIPS(var) FOR_ALL_VEHICLES_OF_TYPE(Ship, var) #endif /* SHIP_H */ diff --git a/src/ship_cmd.cpp b/src/ship_cmd.cpp index ccc0c33b54..142dec0c65 100644 --- a/src/ship_cmd.cpp +++ b/src/ship_cmd.cpp @@ -150,6 +150,9 @@ static void CheckIfShipNeedsService(Vehicle *v) SetWindowWidgetDirty(WC_VEHICLE_VIEW, v->index, VVW_WIDGET_START_STOP_VEH); } +/** + * Update the caches of this ship. + */ void Ship::UpdateCache() { this->vcache.cached_max_speed = GetVehicleProperty(this, PROP_SHIP_SPEED, ShipVehInfo(this->engine_type)->max_speed); diff --git a/src/signal_type.h b/src/signal_type.h index d977958eb1..339ce86db8 100644 --- a/src/signal_type.h +++ b/src/signal_type.h @@ -34,6 +34,7 @@ enum SignalType { SIGTYPE_LAST = SIGTYPE_PBS_ONEWAY, SIGTYPE_LAST_NOPBS = SIGTYPE_COMBO }; +/** Helper information for extract tool. */ template <> struct EnumPropsT : MakeEnumPropsT {}; diff --git a/src/signs.cpp b/src/signs.cpp index 06ea3664c0..2ab678a23c 100644 --- a/src/signs.cpp +++ b/src/signs.cpp @@ -18,7 +18,7 @@ #include "table/strings.h" -/* Initialize the sign-pool */ +/** Initialize the sign-pool */ SignPool _sign_pool("Sign"); INSTANTIATE_POOL_METHODS(Sign) diff --git a/src/signs_cmd.cpp b/src/signs_cmd.cpp index 1b0a8cca2f..c70900fb00 100644 --- a/src/signs_cmd.cpp +++ b/src/signs_cmd.cpp @@ -21,6 +21,7 @@ #include "table/strings.h" +/** The last built sign. */ SignID _new_sign_id; /** diff --git a/src/signs_gui.cpp b/src/signs_gui.cpp index 2c189d705b..d64be87e10 100644 --- a/src/signs_gui.cpp +++ b/src/signs_gui.cpp @@ -638,6 +638,10 @@ static const WindowDesc _query_sign_edit_desc( _nested_query_sign_edit_widgets, lengthof(_nested_query_sign_edit_widgets) ); +/** + * Handle clicking on a sign. + * @param si The sign that was clicked on. + */ void HandleClickOnSign(const Sign *si) { if (_ctrl_pressed && si->owner == _local_company) { @@ -647,6 +651,10 @@ void HandleClickOnSign(const Sign *si) ShowRenameSignWindow(si); } +/** + * Show the window to change the text of a sign. + * @param si The sign to show the window for. + */ void ShowRenameSignWindow(const Sign *si) { /* Delete all other edit windows */ @@ -655,6 +663,10 @@ void ShowRenameSignWindow(const Sign *si) new SignWindow(&_query_sign_edit_desc, si); } +/** + * Close the sign window associated with the given sign. + * @param sign The sign to close the window for. + */ void DeleteRenameSignWindow(SignID sign) { SignWindow *w = dynamic_cast(FindWindowById(WC_QUERY_STRING, 0)); diff --git a/src/signs_type.h b/src/signs_type.h index cbe3752cc6..a539c66899 100644 --- a/src/signs_type.h +++ b/src/signs_type.h @@ -12,10 +12,11 @@ #ifndef SIGNS_TYPE_H #define SIGNS_TYPE_H +/** The type of the IDs of signs. */ typedef uint16 SignID; struct Sign; -static const SignID INVALID_SIGN = 0xFFFF; +static const SignID INVALID_SIGN = 0xFFFF; ///< Sentinel for an invalid sign. static const uint MAX_LENGTH_SIGN_NAME_CHARS = 32; ///< The maximum length of a sign name in characters including '\0' diff --git a/src/slope_type.h b/src/slope_type.h index 5eb7a7a20e..bdf4b78ef6 100644 --- a/src/slope_type.h +++ b/src/slope_type.h @@ -79,6 +79,10 @@ enum Slope { }; DECLARE_ENUM_AS_BIT_SET(Slope) +/** + * Helper for creating a bitset of slopes. + * @param x The slope to convert into a bitset. + */ #define M(x) (1 << (x)) /** Constant bitset with safe slopes for building a level crossing. */ static const uint32 VALID_LEVEL_CROSSING_SLOPES = M(SLOPE_SEN) | M(SLOPE_ENW) | M(SLOPE_NWS) | M(SLOPE_NS) | M(SLOPE_WSE) | M(SLOPE_EW) | M(SLOPE_FLAT); diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp index 2fd86623dc..9f1dd0cdd6 100644 --- a/src/smallmap_gui.cpp +++ b/src/smallmap_gui.cpp @@ -292,6 +292,9 @@ static const SmallMapColourScheme _heightmap_schemes[] = { {_violet_map_heights, MKCOLOUR(0x82828282)}, ///< Violet colour scheme. }; +/** + * (Re)build the colour tables for the legends. + */ void BuildLandLegend() { for (LegendAndColour *lc = _legend_land_contours; lc->legend == STR_TINY_BLACK_HEIGHT; lc++) { @@ -1709,6 +1712,9 @@ static const WindowDesc _smallmap_desc( _nested_smallmap_widgets, lengthof(_nested_smallmap_widgets) ); +/** + * Show the smallmap window. + */ void ShowSmallMap() { AllocateWindowDescFront(&_smallmap_desc, 0); diff --git a/src/sound/null_s.cpp b/src/sound/null_s.cpp index 858724ec38..953bf5764a 100644 --- a/src/sound/null_s.cpp +++ b/src/sound/null_s.cpp @@ -12,4 +12,5 @@ #include "../stdafx.h" #include "null_s.h" +/** The factory for the null sound driver. */ static FSoundDriver_Null iFSoundDriver_Null; diff --git a/src/sound/sdl_s.cpp b/src/sound/sdl_s.cpp index 57ef9ab9d0..7e1c3e9936 100644 --- a/src/sound/sdl_s.cpp +++ b/src/sound/sdl_s.cpp @@ -18,8 +18,15 @@ #include "sdl_s.h" #include +/** Factory for the SDL sound driver. */ static FSoundDriver_SDL iFSoundDriver_SDL; +/** + * Callback that fills the sound buffer. + * @param userdata Ignored. + * @param stream The stream to put data into. + * @param len The length of the stream in bytes. + */ static void CDECL fill_sound_buffer(void *userdata, Uint8 *stream, int len) { MxMixSamples(stream, len / 4); diff --git a/src/spriteloader/spriteloader.hpp b/src/spriteloader/spriteloader.hpp index b159c95a4e..86a87e7a4b 100644 --- a/src/spriteloader/spriteloader.hpp +++ b/src/spriteloader/spriteloader.hpp @@ -15,8 +15,10 @@ #include "../core/alloc_type.hpp" #include "../gfx_type.h" +/** Interface for the loader of our sprites. */ class SpriteLoader { public: + /** Definition of a common pixel in OpenTTD's realm. */ struct CommonPixel { uint8 r; ///< Red-channel uint8 g; ///< Green-channel diff --git a/src/station.cpp b/src/station.cpp index 0cfcf027c0..0f1db371dd 100644 --- a/src/station.cpp +++ b/src/station.cpp @@ -28,6 +28,7 @@ #include "table/strings.h" +/** The pool of stations. */ StationPool _station_pool("Station"); INSTANTIATE_POOL_METHODS(Station) @@ -275,8 +276,8 @@ Rect Station::GetCatchmentRect() const /** Rect and pointer to IndustryVector */ struct RectAndIndustryVector { - Rect rect; - IndustryVector *industries_near; + Rect rect; ///< The rectangle to search the industries in. + IndustryVector *industries_near; ///< The nearby industries. }; /** diff --git a/src/station_map.h b/src/station_map.h index 661cc834c8..1411a7833d 100644 --- a/src/station_map.h +++ b/src/station_map.h @@ -33,8 +33,8 @@ static inline StationID GetStationIndex(TileIndex t) } -static const int GFX_DOCK_BASE_WATER_PART = 4; -static const int GFX_TRUCK_BUS_DRIVETHROUGH_OFFSET = 4; +static const int GFX_DOCK_BASE_WATER_PART = 4; ///< The offset for the water parts. +static const int GFX_TRUCK_BUS_DRIVETHROUGH_OFFSET = 4; ///< The offset for the drive through parts. /** * Get the station type of this tile @@ -476,6 +476,7 @@ static inline bool IsCustomStationSpecIndex(TileIndex t) /** * Set the custom station spec for this tile. * @param t Tile to set the stationspec of. + * @param specindex The new spec. * @pre HasStationTileRail(t) */ static inline void SetCustomStationSpecIndex(TileIndex t, byte specindex) @@ -498,7 +499,8 @@ static inline uint GetCustomStationSpecIndex(TileIndex t) /** * Set the random bits for a station tile. - * @param t Tile to set random bits for + * @param t Tile to set random bits for. + * @param random_bits The random bits. * @pre IsTileType(t, MP_STATION) */ static inline void SetStationTileRandomBits(TileIndex t, byte random_bits) @@ -526,6 +528,7 @@ static inline byte GetStationTileRandomBits(TileIndex t) * @param sid the station to which this tile belongs * @param st the type this station tile * @param section the StationGfx to be used for this tile + * @param wc The water class of the station */ static inline void MakeStation(TileIndex t, Owner o, StationID sid, StationType st, byte section, WaterClass wc = WATER_CLASS_INVALID) { @@ -599,7 +602,7 @@ static inline void MakeRoadStop(TileIndex t, Owner o, StationID sid, RoadStopTyp * @param sid the station to which this tile belongs * @param rst the type of roadstop to make this tile * @param rt the roadtypes on this tile - * @param d the direction of the roadstop + * @param a the direction of the roadstop */ static inline void MakeDriveThroughRoadStop(TileIndex t, Owner station, Owner road, Owner tram, StationID sid, RoadStopType rst, RoadTypes rt, Axis a) { diff --git a/src/statusbar_gui.cpp b/src/statusbar_gui.cpp index 82ffeb2393..14e2dc0d8b 100644 --- a/src/statusbar_gui.cpp +++ b/src/statusbar_gui.cpp @@ -257,6 +257,9 @@ bool IsNewsTickerShown() int16 *_preferred_statusbar_size = &_main_status_desc.default_width; ///< Pointer to the default size for the status toolbar. +/** + * Show our status bar. + */ void ShowStatusBar() { new StatusBarWindow(&_main_status_desc); diff --git a/src/statusbar_gui.h b/src/statusbar_gui.h index 2ec4e895a6..7852c7803b 100644 --- a/src/statusbar_gui.h +++ b/src/statusbar_gui.h @@ -12,6 +12,7 @@ #ifndef STATUSBAR_GUI_H #define STATUSBAR_GUI_H +/** What of the statusbar must be invalidated? */ enum StatusBarInvalidate { SBI_SAVELOAD_START, ///< started saving SBI_SAVELOAD_FINISH, ///< finished saving diff --git a/src/string.cpp b/src/string.cpp index 1ba6f15fbb..7aa081c452 100644 --- a/src/string.cpp +++ b/src/string.cpp @@ -160,7 +160,11 @@ char *strecpy(char *dst, const char *src, const char *last) return dst; } - +/** + * Format, "printf", into a newly allocated string. + * @param str The formatting string. + * @return The formatted string. You must free this! + */ char *CDECL str_fmt(const char *str, ...) { char buf[4096]; diff --git a/src/string_type.h b/src/string_type.h index 9532c86ad5..b2bd6824d9 100644 --- a/src/string_type.h +++ b/src/string_type.h @@ -29,6 +29,7 @@ enum CharSetFilter { CS_HEXADECIMAL, ///< Only hexadecimal characters }; +/** Type for wide characters, i.e. non-UTF8 encoded unicode characters. */ typedef uint32 WChar; /* The following are directional formatting codes used to get the LTR and RTL strings right: diff --git a/src/subsidy_type.h b/src/subsidy_type.h index 734d72103a..83c33a00a9 100644 --- a/src/subsidy_type.h +++ b/src/subsidy_type.h @@ -20,6 +20,7 @@ enum PartOfSubsidy { POS_SRC = 1 << 0, ///< bit 0 set -> town/industry is source of subsidised path POS_DST = 1 << 1, ///< bit 1 set -> town/industry is destination of subsidised path }; +/** Helper to store the PartOfSubsidy data in a single byte. */ typedef SimpleTinyEnumT PartOfSubsidyByte; DECLARE_ENUM_AS_BIT_SET(PartOfSubsidy) diff --git a/src/waypoint_gui.cpp b/src/waypoint_gui.cpp index bca642b3d7..0ece60177f 100644 --- a/src/waypoint_gui.cpp +++ b/src/waypoint_gui.cpp @@ -54,6 +54,11 @@ private: } public: + /** + * Construct the window. + * @param desc The description of the window. + * @param window_number The window number, in this case the waypoint's ID. + */ WaypointWindow(const WindowDesc *desc, WindowNumber window_number) : Window() { this->wp = Waypoint::Get(window_number);