From 2ac0811ff9a2bf7e52626c6540759fbaacb50fb4 Mon Sep 17 00:00:00 2001 From: Cyprian Klimaszewski Date: Fri, 20 Feb 2026 20:00:43 +0100 Subject: [PATCH] Codechange: Make documentation comments for some functions recognised by doxygen. --- src/build_vehicle_gui.cpp | 8 ++++---- src/console_cmds.cpp | 5 +---- src/disaster_vehicle.cpp | 9 ++++----- src/highscore_gui.cpp | 2 +- src/network/network.cpp | 21 +++++++++++++-------- src/newgrf.cpp | 2 +- src/newgrf_house.cpp | 2 +- src/saveload/afterload.cpp | 4 ++-- src/saveload/company_sl.cpp | 2 +- src/saveload/gamelog_sl.cpp | 2 +- src/saveload/linkgraph_sl.cpp | 2 +- src/story_gui.cpp | 4 ++-- src/tree_cmd.cpp | 2 +- 13 files changed, 33 insertions(+), 32 deletions(-) diff --git a/src/build_vehicle_gui.cpp b/src/build_vehicle_gui.cpp index 5fac9830aa..5a37932347 100644 --- a/src/build_vehicle_gui.cpp +++ b/src/build_vehicle_gui.cpp @@ -1486,7 +1486,7 @@ struct BuildVehicleWindow : Window { EngList_SortPartial(list, _engine_sort_functions[0][this->sort_criteria], num_engines, list.size() - num_engines); } - /* Figure out what road vehicle EngineIDs to put in the list */ + /** Figure out what road vehicle EngineIDs to put in the list. */ void GenerateBuildRoadVehList() { EngineID sel_id = EngineID::Invalid(); @@ -1513,7 +1513,7 @@ struct BuildVehicleWindow : Window { this->SelectEngine(sel_id); } - /* Figure out what ship EngineIDs to put in the list */ + /** Figure out what ship EngineIDs to put in the list. */ void GenerateBuildShipList() { EngineID sel_id = EngineID::Invalid(); @@ -1538,7 +1538,7 @@ struct BuildVehicleWindow : Window { this->SelectEngine(sel_id); } - /* Figure out what aircraft EngineIDs to put in the list */ + /** Figure out what aircraft EngineIDs to put in the list. */ void GenerateBuildAircraftList() { EngineID sel_id = EngineID::Invalid(); @@ -1573,7 +1573,7 @@ struct BuildVehicleWindow : Window { this->SelectEngine(sel_id); } - /* Generate the list of vehicles */ + /** Generate the list of vehicles. */ void GenerateBuildList() { if (!this->eng_list.NeedRebuild()) return; diff --git a/src/console_cmds.cpp b/src/console_cmds.cpp index 9c0cdde126..c2a4664ac3 100644 --- a/src/console_cmds.cpp +++ b/src/console_cmds.cpp @@ -2957,10 +2957,7 @@ static bool ConDumpInfo(std::span argv) return false; } -/******************************* - * console command registration - *******************************/ - +/** Console command registration. */ void IConsoleStdLibRegister() { IConsole::CmdRegister("debug_level", ConDebugLevel); diff --git a/src/disaster_vehicle.cpp b/src/disaster_vehicle.cpp index 1978b69dab..b7b446a893 100644 --- a/src/disaster_vehicle.cpp +++ b/src/disaster_vehicle.cpp @@ -780,7 +780,7 @@ static void Disaster_Small_Ufo_Init() } -/* Combat airplane which destroys an oil refinery */ +/** Combat airplane which destroys an oil refinery. */ static void Disaster_Airplane_Init() { if (!Vehicle::CanAllocateItem(2)) return; @@ -834,8 +834,7 @@ static void Disaster_Helicopter_Init() } -/* Big Ufo which lands on a piece of rail and will consequently be shot - * down by a combat airplane, destroying the surroundings */ +/** Big Ufo which lands on a piece of rail and will consequently be shot down by a combat airplane, destroying the surroundings. */ static void Disaster_Big_Ufo_Init() { if (!Vehicle::CanAllocateItem(2)) return; @@ -878,14 +877,14 @@ static void Disaster_Submarine_Init(DisasterSubType subtype) DisasterVehicle::Create(x, y, dir, subtype); } -/* Curious submarine #1, just floats around */ +/** Curious submarine #1, just floats around. */ static void Disaster_Small_Submarine_Init() { Disaster_Submarine_Init(ST_SMALL_SUBMARINE); } -/* Curious submarine #2, just floats around */ +/** Curious submarine #2, just floats around. */ static void Disaster_Big_Submarine_Init() { Disaster_Submarine_Init(ST_BIG_SUBMARINE); diff --git a/src/highscore_gui.cpp b/src/highscore_gui.cpp index 807c1de761..3644aa21a9 100644 --- a/src/highscore_gui.cpp +++ b/src/highscore_gui.cpp @@ -41,7 +41,7 @@ struct EndGameHighScoreBaseWindow : Window { ResizeWindow(this, _screen.width - this->width, _screen.height - this->height); } - /* Always draw a maximized window and within it the centered background */ + /** Always draw a maximized window and within it the centered background. */ void SetupHighScoreEndWindow() { /* Resize window to "full-screen". */ diff --git a/src/network/network.cpp b/src/network/network.cpp index 259a40b269..a3bc1d6e7b 100644 --- a/src/network/network.cpp +++ b/src/network/network.cpp @@ -727,9 +727,10 @@ void GetBindAddresses(NetworkAddressList *addresses, uint16_t port) } } -/* Generates the list of manually added hosts from NetworkGame and - * dumps them into the array _network_host_list. This array is needed - * by the function that generates the config file. */ +/** + * Generates the list of manually added hosts from NetworkGame and dumps them into the array _network_host_list. + * This array is needed by the function that generates the config file. + */ void NetworkRebuildHostList() { _network_host_list.clear(); @@ -971,8 +972,10 @@ void NetworkOnGameStart() } } -/* The server is rebooting... - * The only difference with NetworkDisconnect, is the packets that is sent */ +/** + * The server is rebooting... + * The only difference with NetworkDisconnect, is the packets that is sent. + */ void NetworkReboot() { if (_network_server) { @@ -1060,7 +1063,7 @@ static bool NetworkReceive() return result; } -/* This sends all buffered commands (if possible) */ +/** This sends all buffered commands (if possible). */ static void NetworkSend() { if (_network_server) { @@ -1089,8 +1092,10 @@ void NetworkBackgroundLoop() NetworkBackgroundUDPLoop(); } -/* The main loop called from ttd.c - * Here we also have to do StateGameLoop if needed! */ +/** + * The main loop called from ttd.c. + * @note Here we also have to do StateGameLoop if needed! + */ void NetworkGameLoop() { if (!_networking) return; diff --git a/src/newgrf.cpp b/src/newgrf.cpp index b4eb542ab5..bc2cb8aff4 100644 --- a/src/newgrf.cpp +++ b/src/newgrf.cpp @@ -82,7 +82,7 @@ TypedIndexContainer, EngineID> _gted; ///< Tempo * Debug() function dedicated to newGRF debugging messages * Function is essentially the same as Debug(grf, severity, ...) with the * addition of file:line information when parsing grf files. - * NOTE: for the above reason(s) GrfMsg() should ONLY be used for + * @note for the above reason(s) GrfMsg() should ONLY be used for * loading/parsing grf files, not for runtime debug messages as there * is no file information available during that time. * @param severity debugging severity level, see debug.h diff --git a/src/newgrf_house.cpp b/src/newgrf_house.cpp index 539adb6d8f..6d0f4de97b 100644 --- a/src/newgrf_house.cpp +++ b/src/newgrf_house.cpp @@ -77,7 +77,7 @@ HouseSpec *HouseSpec::Get(size_t house_id) return &_house_specs[house_id]; } -/* Reset and initialise house specs. */ +/** Reset and initialise house specs. */ void ResetHouses() { _house_specs.clear(); diff --git a/src/saveload/afterload.cpp b/src/saveload/afterload.cpp index bb36c48caf..d21f790a5e 100644 --- a/src/saveload/afterload.cpp +++ b/src/saveload/afterload.cpp @@ -178,7 +178,7 @@ static void ConvertTownOwner() } } -/* since savegame version 4.1, exclusive transport rights are stored at towns */ +/** Since savegame version 4.1, exclusive transport rights are stored at towns. */ static void UpdateExclusiveRights() { for (Town *t : Town::Iterate()) { @@ -194,7 +194,7 @@ static const uint8_t convert_currency[] = { 18, 2, 20, }; -/* since savegame version 4.2 the currencies are arranged differently */ +/** Since savegame version 4.2 the currencies are arranged differently. */ static void UpdateCurrencies() { _settings_game.locale.currency = convert_currency[_settings_game.locale.currency]; diff --git a/src/saveload/company_sl.cpp b/src/saveload/company_sl.cpp index ff2bc4ccb8..6cb81c8488 100644 --- a/src/saveload/company_sl.cpp +++ b/src/saveload/company_sl.cpp @@ -276,7 +276,7 @@ struct CompanyOldAI { class SlCompanyOldAIBuildRec : public DefaultSaveLoadHandler { public: - static inline const SaveLoad description[] = {{}}; // Needed to keep DefaultSaveLoadHandler happy. + static inline const SaveLoad description[] = {{}}; ///< Needed to keep DefaultSaveLoadHandler happy. static inline const SaveLoadCompatTable compat_description = _company_old_ai_buildrec_compat; SaveLoadTable GetDescription() const override { return {}; } diff --git a/src/saveload/gamelog_sl.cpp b/src/saveload/gamelog_sl.cpp index 2a5372b5bc..af690b45d5 100644 --- a/src/saveload/gamelog_sl.cpp +++ b/src/saveload/gamelog_sl.cpp @@ -265,7 +265,7 @@ static bool _is_emergency_save = true; class SlGamelogEmergency : public DefaultSaveLoadHandler { public: - /* We need to store something, so store a "true" value. */ + /** We need to store something, so store a "true" value. */ static inline const SaveLoad description[] = { SLEG_CONDVAR("is_emergency_save", _is_emergency_save, SLE_BOOL, SLV_RIFF_TO_ARRAY, SL_MAX_VERSION), }; diff --git a/src/saveload/linkgraph_sl.cpp b/src/saveload/linkgraph_sl.cpp index da40832f3c..28fccbb544 100644 --- a/src/saveload/linkgraph_sl.cpp +++ b/src/saveload/linkgraph_sl.cpp @@ -153,7 +153,7 @@ SaveLoadTable GetLinkGraphDesc() */ class SlLinkgraphJobProxy : public DefaultSaveLoadHandler { public: - static inline const SaveLoad description[] = {{}}; // Needed to keep DefaultSaveLoadHandler happy. + static inline const SaveLoad description[] = {{}}; ///< Needed to keep DefaultSaveLoadHandler happy. SaveLoadTable GetDescription() const override { return GetLinkGraphDesc(); } static inline const SaveLoadCompatTable compat_description = _linkgraph_sl_compat; diff --git a/src/story_gui.cpp b/src/story_gui.cpp index fe6419a7c3..b7daf09cbc 100644 --- a/src/story_gui.cpp +++ b/src/story_gui.cpp @@ -117,10 +117,10 @@ protected: return a->sort_value < b->sort_value; } - /* + /** * Checks if a given page should be visible in the story book. * @param page The page to check. - * @return True if the page should be visible, otherwise false. + * @return \c true iff the page should be visible. */ bool IsPageAvailable(const StoryPage *page) const { diff --git a/src/tree_cmd.cpp b/src/tree_cmd.cpp index 7fd20d71d9..2f1737cb4f 100644 --- a/src/tree_cmd.cpp +++ b/src/tree_cmd.cpp @@ -810,7 +810,7 @@ static void TileLoopTreesAlps(TileIndex tile) MarkTileDirtyByTile(tile); } -/* +/** * Check if trees on this tile are allowed to spread. * If they are allowed to spread, they are also allowed to die. * @param tile The tile to check.