From 8e75626b49868dca69d5a5f2bfcb2e549e00a3ac Mon Sep 17 00:00:00 2001 From: Rubidium Date: Sun, 8 Feb 2026 19:49:37 +0100 Subject: [PATCH] Codechange: unify documentation and parameter names of sorters --- src/autoreplace_gui.cpp | 1 + src/bridge_gui.cpp | 6 +- src/build_vehicle_gui.cpp | 112 ++++------------------------ src/cargotype.cpp | 4 +- src/highscore.cpp | 2 +- src/industry_gui.cpp | 12 +-- src/league_gui.cpp | 6 +- src/network/network_content_gui.cpp | 6 +- src/network/network_gui.cpp | 10 ++- src/newgrf_config.cpp | 10 +-- src/newgrf_gui.cpp | 2 +- src/picker_gui.cpp | 11 +-- src/signs_gui.cpp | 2 +- src/sortlist_type.h | 17 +++++ src/station_gui.cpp | 32 ++++---- src/story_gui.cpp | 4 +- src/timetable_cmd.cpp | 5 +- src/town_gui.cpp | 22 +++--- src/vehicle_gui.cpp | 38 +++++----- src/window.cpp | 4 +- 20 files changed, 116 insertions(+), 190 deletions(-) diff --git a/src/autoreplace_gui.cpp b/src/autoreplace_gui.cpp index ed15d13d9a..65e9a1d8f0 100644 --- a/src/autoreplace_gui.cpp +++ b/src/autoreplace_gui.cpp @@ -37,6 +37,7 @@ #include "safeguards.h" +/** Compare the (NewGRF) list position. @copydoc GUIList::Sorter. */ static bool EngineNumberSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { return Engine::Get(a.engine_id)->list_position < Engine::Get(b.engine_id)->list_position; diff --git a/src/bridge_gui.cpp b/src/bridge_gui.cpp index 8bfecf460f..a8423f3c08 100644 --- a/src/bridge_gui.cpp +++ b/src/bridge_gui.cpp @@ -91,19 +91,19 @@ private: int icon_width = 0; ///< Scaled width of the the bridge icon sprite. Scrollbar *vscroll = nullptr; - /** Sort the bridges by their index */ + /** Sort the bridges by their index. @copydoc GUIList::Sorter */ static bool BridgeIndexSorter(const BuildBridgeData &a, const BuildBridgeData &b) { return a.index < b.index; } - /** Sort the bridges by their price */ + /** Sort the bridges by their price. @copydoc GUIList::Sorter */ static bool BridgePriceSorter(const BuildBridgeData &a, const BuildBridgeData &b) { return a.cost < b.cost; } - /** Sort the bridges by their maximum speed */ + /** Sort the bridges by their maximum speed. @copydoc GUIList::Sorter */ static bool BridgeSpeedSorter(const BuildBridgeData &a, const BuildBridgeData &b) { return a.spec->speed < b.spec->speed; diff --git a/src/build_vehicle_gui.cpp b/src/build_vehicle_gui.cpp index 3a1fa77102..7ff7182fc1 100644 --- a/src/build_vehicle_gui.cpp +++ b/src/build_vehicle_gui.cpp @@ -107,12 +107,7 @@ bool _engine_sort_last_order[] = {false, false, false, false}; ///< Las bool _engine_sort_show_hidden_engines[] = {false, false, false, false}; ///< Last set 'show hidden engines' setting for each vehicle type. static CargoType _engine_sort_last_cargo_criteria[] = {CargoFilterCriteria::CF_ANY, CargoFilterCriteria::CF_ANY, CargoFilterCriteria::CF_ANY, CargoFilterCriteria::CF_ANY}; ///< Last set filter criteria, for each vehicle type. -/** - * Determines order of engines by engineID - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by engineID. @copydoc GUIList::Sorter */ static bool EngineNumberSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int r = Engine::Get(a.engine_id)->list_position - Engine::Get(b.engine_id)->list_position; @@ -120,12 +115,7 @@ static bool EngineNumberSorter(const GUIEngineListItem &a, const GUIEngineListIt return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by introduction date - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by introduction date. @copydoc GUIList::Sorter */ static bool EngineIntroDateSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const auto va = Engine::Get(a.engine_id)->intro_date; @@ -140,12 +130,7 @@ static bool EngineIntroDateSorter(const GUIEngineListItem &a, const GUIEngineLis /* cached values for EngineNameSorter to spare many GetString() calls */ static EngineID _last_engine[2] = { EngineID::Invalid(), EngineID::Invalid() }; -/** - * Determines order of engines by name - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by name. @copydoc GUIList::Sorter */ static bool EngineNameSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { static std::string last_name[2] = { {}, {} }; @@ -167,12 +152,7 @@ static bool EngineNameSorter(const GUIEngineListItem &a, const GUIEngineListItem return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by reliability - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by reliability. @copydoc GUIList::Sorter */ static bool EngineReliabilitySorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const int va = Engine::Get(a.engine_id)->reliability; @@ -184,12 +164,7 @@ static bool EngineReliabilitySorter(const GUIEngineListItem &a, const GUIEngineL return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by purchase cost - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by purchase cost. @copydoc GUIList::Sorter */ static bool EngineCostSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { Money va = Engine::Get(a.engine_id)->GetCost(); @@ -201,12 +176,7 @@ static bool EngineCostSorter(const GUIEngineListItem &a, const GUIEngineListItem return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by speed - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by speed. @copydoc GUIList::Sorter */ static bool EngineSpeedSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int va = Engine::Get(a.engine_id)->GetDisplayMaxSpeed(); @@ -218,12 +188,7 @@ static bool EngineSpeedSorter(const GUIEngineListItem &a, const GUIEngineListIte return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by power - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by power. @copydoc GUIList::Sorter */ static bool EnginePowerSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int va = Engine::Get(a.engine_id)->GetPower(); @@ -235,12 +200,7 @@ static bool EnginePowerSorter(const GUIEngineListItem &a, const GUIEngineListIte return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by tractive effort - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by tractive effort. @copydoc GUIList::Sorter */ static bool EngineTractiveEffortSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int va = Engine::Get(a.engine_id)->GetDisplayMaxTractiveEffort(); @@ -252,12 +212,7 @@ static bool EngineTractiveEffortSorter(const GUIEngineListItem &a, const GUIEngi return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by running costs - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by running costs. @copydoc GUIList::Sorter */ static bool EngineRunningCostSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { Money va = Engine::Get(a.engine_id)->GetRunningCost(); @@ -269,12 +224,7 @@ static bool EngineRunningCostSorter(const GUIEngineListItem &a, const GUIEngineL return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of engines by running costs - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of engines by running costs. @copydoc GUIList::Sorter */ static bool EnginePowerVsRunningCostSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const Engine *e_a = Engine::Get(a.engine_id); @@ -311,12 +261,7 @@ static bool EnginePowerVsRunningCostSorter(const GUIEngineListItem &a, const GUI /* Train sorting functions */ -/** - * Determines order of train engines by capacity - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of train engines by capacity. @copydoc GUIList::Sorter */ static bool TrainEngineCapacitySorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const RailVehicleInfo *rvi_a = RailVehInfo(a.engine_id); @@ -331,12 +276,7 @@ static bool TrainEngineCapacitySorter(const GUIEngineListItem &a, const GUIEngin return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of train engines by engine / wagon - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of train engines by engine / wagon. @copydoc GUIList::Sorter */ static bool TrainEnginesThenWagonsSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int val_a = (RailVehInfo(a.engine_id)->railveh_type == RAILVEH_WAGON ? 1 : 0); @@ -350,12 +290,7 @@ static bool TrainEnginesThenWagonsSorter(const GUIEngineListItem &a, const GUIEn /* Road vehicle sorting functions */ -/** - * Determines order of road vehicles by capacity - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of road vehicles by capacity. @copydoc GUIList::Sorter */ static bool RoadVehEngineCapacitySorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { int va = GetTotalCapacityOfArticulatedParts(a.engine_id); @@ -369,12 +304,7 @@ static bool RoadVehEngineCapacitySorter(const GUIEngineListItem &a, const GUIEng /* Ship vehicle sorting functions */ -/** - * Determines order of ships by capacity - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of ships by capacity. @copydoc GUIList::Sorter */ static bool ShipEngineCapacitySorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const Engine *e_a = Engine::Get(a.engine_id); @@ -391,12 +321,7 @@ static bool ShipEngineCapacitySorter(const GUIEngineListItem &a, const GUIEngine /* Aircraft sorting functions */ -/** - * Determines order of aircraft by cargo - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of aircraft by cargo. @copydoc GUIList::Sorter */ static bool AircraftEngineCargoSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { const Engine *e_a = Engine::Get(a.engine_id); @@ -419,12 +344,7 @@ static bool AircraftEngineCargoSorter(const GUIEngineListItem &a, const GUIEngin return _engine_sort_direction ? r > 0 : r < 0; } -/** - * Determines order of aircraft by range. - * @param a first engine to compare - * @param b second engine to compare - * @return for descending order: returns true if a < b. Vice versa for ascending order - */ +/** Determines order of aircraft by range. @copydoc GUIList::Sorter */ static bool AircraftRangeSorter(const GUIEngineListItem &a, const GUIEngineListItem &b) { uint16_t r_a = Engine::Get(a.engine_id)->GetRange(); diff --git a/src/cargotype.cpp b/src/cargotype.cpp index 6a397675cf..b8714696ba 100644 --- a/src/cargotype.cpp +++ b/src/cargotype.cpp @@ -190,7 +190,7 @@ std::array _sorted_cargo_types; ///< Sort order of cargoes b std::vector _sorted_cargo_specs; ///< Cargo specifications sorted alphabetically by name. std::span _sorted_standard_cargo_specs; ///< Standard cargo specifications sorted alphabetically by name. -/** Sort cargo specifications by their name. */ +/** Sort cargo specifications by their name. @copydoc GUIList::Sorter */ static bool CargoSpecNameSorter(const CargoSpec * const &a, const CargoSpec * const &b) { std::string a_name = GetString(a->name); @@ -202,7 +202,7 @@ static bool CargoSpecNameSorter(const CargoSpec * const &a, const CargoSpec * co return (res != 0) ? res < 0 : (a->bitnum < b->bitnum); } -/** Sort cargo specifications by their cargo class. */ +/** Sort cargo specifications by their cargo class. @copydoc GUIList::Sorter */ static bool CargoSpecClassSorter(const CargoSpec * const &a, const CargoSpec * const &b) { int res = b->classes.Test(CargoClass::Passengers) - a->classes.Test(CargoClass::Passengers); diff --git a/src/highscore.cpp b/src/highscore.cpp index 397c157f64..8a15aa5507 100644 --- a/src/highscore.cpp +++ b/src/highscore.cpp @@ -75,7 +75,7 @@ int8_t SaveHighScoreValue(const Company *c) return std::distance(highscores.begin(), it); } -/** Sort all companies given their performance */ +/** Sort all companies given their performance. @copydoc GUIList::Sorter */ static bool HighScoreSorter(const Company * const &a, const Company * const &b) { return b->old_economy[0].performance_history < a->old_economy[0].performance_history; diff --git a/src/industry_gui.cpp b/src/industry_gui.cpp index 8190d04e99..632f74f8e1 100644 --- a/src/industry_gui.cpp +++ b/src/industry_gui.cpp @@ -234,7 +234,7 @@ void GetCargoSuffix(CargoSuffixInOut use_input, CargoSuffixType cst, const Indus std::array _sorted_industry_types; ///< Industry types sorted by name. -/** Sort industry types by their name. */ +/** Sort industry types by their name. @copydoc GUIList::Sorter */ static bool IndustryTypeNameSorter(const IndustryType &a, const IndustryType &b) { int r = StrNaturalCompare(GetString(GetIndustrySpec(a)->name), GetString(GetIndustrySpec(b)->name)); // Sort by name (natural sorting). @@ -1499,15 +1499,15 @@ protected: return percentage / produced_cargo_count; } - /** Sort industries by name */ - static bool IndustryNameSorter(const Industry * const &a, const Industry * const &b, const CargoType &) + /** Sort industries by name. @copydoc GUIList::SorterWithFilter */ + static bool IndustryNameSorter(const Industry * const &a, const Industry * const &b, [[maybe_unused]] const CargoType &filter) { int r = StrNaturalCompare(a->GetCachedName(), b->GetCachedName()); // Sort by name (natural sorting). if (r == 0) return a->index < b->index; return r < 0; } - /** Sort industries by type and name */ + /** Sort industries by type and name. @copydoc GUIList::SorterWithFilter */ static bool IndustryTypeSorter(const Industry * const &a, const Industry * const &b, const CargoType &filter) { int it_a = 0; @@ -1518,7 +1518,7 @@ protected: return (r == 0) ? IndustryNameSorter(a, b, filter) : r < 0; } - /** Sort industries by production and name */ + /** Sort industries by production and name. @copydoc GUIList::SorterWithFilter */ static bool IndustryProductionSorter(const Industry * const &a, const Industry * const &b, const CargoType &filter) { if (filter == CargoFilterCriteria::CF_NONE) return IndustryTypeSorter(a, b, filter); @@ -1540,7 +1540,7 @@ protected: return (r == 0) ? IndustryTypeSorter(a, b, filter) : r < 0; } - /** Sort industries by transported cargo and name */ + /** Sort industries by transported cargo and name. @copydoc GUIList::SorterWithFilter */ static bool IndustryTransportedCargoSorter(const Industry * const &a, const Industry * const &b, const CargoType &filter) { int r = GetCargoTransportedSortValue(a) - GetCargoTransportedSortValue(b); diff --git a/src/league_gui.cpp b/src/league_gui.cpp index 24bcf8b4b0..04973308d6 100644 --- a/src/league_gui.cpp +++ b/src/league_gui.cpp @@ -79,10 +79,10 @@ private: this->companies.RebuildDone(); } - /** Sort the company league by performance history */ - static bool PerformanceSorter(const Company * const &c1, const Company * const &c2) + /** Sort the company league by performance history. @copydoc GUIList::Sorter */ + static bool PerformanceSorter(const Company * const &a, const Company * const &b) { - return c2->old_economy[0].performance_history < c1->old_economy[0].performance_history; + return b->old_economy[0].performance_history < a->old_economy[0].performance_history; } public: diff --git a/src/network/network_content_gui.cpp b/src/network/network_content_gui.cpp index 914b630cba..b88e8a73f8 100644 --- a/src/network/network_content_gui.cpp +++ b/src/network/network_content_gui.cpp @@ -423,7 +423,7 @@ class NetworkContentListWindow : public Window, ContentCallback { this->ScrollToSelected(); } - /** Sort content by name. */ + /** Sort content by name. @copydoc GUIList::Sorter */ static bool NameSorter(const ContentInfo * const &a, const ContentInfo * const &b) { int r = StrNaturalCompare(a->name, b->name, true); // Sort by name (natural sorting). @@ -431,7 +431,7 @@ class NetworkContentListWindow : public Window, ContentCallback { return r < 0; } - /** Sort content by type. */ + /** Sort content by type. @copydoc GUIList::Sorter */ static bool TypeSorter(const ContentInfo * const &a, const ContentInfo * const &b) { int r = 0; @@ -442,7 +442,7 @@ class NetworkContentListWindow : public Window, ContentCallback { return r < 0; } - /** Sort content by state. */ + /** Sort content by state. @copydoc GUIList::Sorter */ static bool StateSorter(const ContentInfo * const &a, const ContentInfo * const &b) { int r = to_underlying(a->state) - to_underlying(b->state); diff --git a/src/network/network_gui.cpp b/src/network/network_gui.cpp index 51c286cfc5..05d985edd4 100644 --- a/src/network/network_gui.cpp +++ b/src/network/network_gui.cpp @@ -245,7 +245,7 @@ protected: this->UpdateListPos(); } - /** Sort servers by name. */ + /** Sort servers by name. @copydoc GUIList::Sorter */ static bool NGameNameSorter(NetworkGame * const &a, NetworkGame * const &b) { int r = StrNaturalCompare(a->info.server_name, b->info.server_name, true); // Sort by name (natural sorting). @@ -258,6 +258,7 @@ protected: * Sort servers by the amount of clients online on a * server. If the two servers have the same amount, the one with the * higher maximum is preferred. + * @copydoc GUIList::Sorter */ static bool NGameClientSorter(NetworkGame * const &a, NetworkGame * const &b) { @@ -270,7 +271,7 @@ protected: return r < 0; } - /** Sort servers by map size */ + /** Sort servers by map size. @copydoc GUIList::Sorter */ static bool NGameMapSizeSorter(NetworkGame * const &a, NetworkGame * const &b) { /* Sort by the area of the map. */ @@ -280,14 +281,14 @@ protected: return (r != 0) ? r < 0 : NGameClientSorter(a, b); } - /** Sort servers by calendar date. */ + /** Sort servers by calendar date. @copydoc GUIList::Sorter */ static bool NGameCalendarDateSorter(NetworkGame * const &a, NetworkGame * const &b) { auto r = a->info.calendar_date - b->info.calendar_date; return (r != 0) ? r < 0 : NGameClientSorter(a, b); } - /** Sort servers by the number of ticks the game is running. */ + /** Sort servers by the number of ticks the game is running. @copydoc GUIList::Sorter */ static bool NGameTicksPlayingSorter(NetworkGame * const &a, NetworkGame * const &b) { if (a->info.ticks_playing == b->info.ticks_playing) { @@ -299,6 +300,7 @@ protected: /** * Sort servers by joinability. If both servers are the * same, prefer the non-passworded server first. + * @copydoc GUIList::Sorter */ static bool NGameAllowedSorter(NetworkGame * const &a, NetworkGame * const &b) { diff --git a/src/newgrf_config.cpp b/src/newgrf_config.cpp index e524fdefc3..7518312cce 100644 --- a/src/newgrf_config.cpp +++ b/src/newgrf_config.cpp @@ -535,14 +535,10 @@ bool GRFFileScanner::AddFile(const std::string &filename, size_t basepath_length } /** - * Simple sorter for GRFS - * @param c1 the first GRFConfig * - * @param c2 the second GRFConfig * - * @return true if the name of first NewGRF is before the name of the second. - */ -static bool GRFSorter(std::unique_ptr const &c1, std::unique_ptr const &c2) + * Simple sorter for GRFS. @copydoc GUIList::Sorter */ +static bool GRFSorter(std::unique_ptr const &a, std::unique_ptr const &b) { - return StrNaturalCompare(c1->GetName(), c2->GetName()) < 0; + return StrNaturalCompare(a->GetName(), b->GetName()) < 0; } /** diff --git a/src/newgrf_gui.cpp b/src/newgrf_gui.cpp index 8a210028b6..d3734972cf 100644 --- a/src/newgrf_gui.cpp +++ b/src/newgrf_gui.cpp @@ -1387,7 +1387,7 @@ struct NewGRFWindow : public Window, NewGRFScanCallback { } private: - /** Sort grfs by name. */ + /** Sort grfs by name. @copydoc GUIList::Sorter */ static bool NameSorter(const GRFConfig * const &a, const GRFConfig * const &b) { std::string name_a = StrMakeValid(a->GetName(), {}); // Make a copy without control codes. diff --git a/src/picker_gui.cpp b/src/picker_gui.cpp index 780f83cc3b..9f915924d5 100644 --- a/src/picker_gui.cpp +++ b/src/picker_gui.cpp @@ -142,7 +142,7 @@ void PickerSaveConfig(IniFile &ini) for (const auto *cb : GetPickerCallbacks()) PickerSaveConfig(ini, *cb); } -/** Sort classes by id. */ +/** Sort classes by id. @copydoc GUIList::Sorter */ static bool ClassIDSorter(int const &a, int const &b) { return a < b; @@ -156,7 +156,7 @@ static bool ClassTagNameFilter(int const *item, PickerFilterData &filter) return filter.GetState(); } -/** Sort types by id. */ +/** Sort types by id. @copydoc GUIList::Sorter */ static bool TypeIDSorter(PickerItem const &a, PickerItem const &b) { int r = a.class_index - b.class_index; @@ -179,12 +179,7 @@ static bool TypeTagNameFilter(PickerItem const *item, PickerFilterData &filter) /** Allow the collection sorter to test if the collection has inactive items */ PickerWindow *picker_window; -/** - * Sort collections by id. - * @param a First string for sorting. - * @param b Second string for sorting. - * @return Sort order. - */ +/** Sort collections by id. @copydoc GUIList::Sorter */ static bool CollectionIDSorter(std::string const &a, std::string const &b) { if (a == GetString(STR_PICKER_DEFAULT_COLLECTION) || b == GetString(STR_PICKER_DEFAULT_COLLECTION)) return a == GetString(STR_PICKER_DEFAULT_COLLECTION); diff --git a/src/signs_gui.cpp b/src/signs_gui.cpp index a7b6482588..2a7dd6ea6e 100644 --- a/src/signs_gui.cpp +++ b/src/signs_gui.cpp @@ -75,7 +75,7 @@ struct SignList { this->signs.RebuildDone(); } - /** Sort signs by their name */ + /** Sort signs by their name. @copydoc GUIList::Sorter */ static bool SignNameSorter(const Sign * const &a, const Sign * const &b) { /* Signs are very very rarely using the default text, but there can also be diff --git a/src/sortlist_type.h b/src/sortlist_type.h index 47226abeed..44dfc71eb6 100644 --- a/src/sortlist_type.h +++ b/src/sortlist_type.h @@ -42,6 +42,23 @@ struct Filtering { template class GUIList : public std::vector { public: + /** + * Comparison helper for the sorter, comparing \c a to \c b. + * @param a The first element. + * @param b The second element. + * @return \c true if the first element is less than the second element. + */ + using Sorter = bool (const T &a, const T &b); + + /** + * Comparison helper for the sorter, comparing \c a to \c b taking the \c filter ino consideration. + * @param a The first element. + * @param b The second element. + * @param filter Filter parameter for a subsection of the data, e.g. a specific cargo type when comparing industry production. + * @return \c true if the first element is less than the second element. + */ + using SorterWithFilter = bool(const T &a, const T &b, const P filter); + using SortFunction = std::conditional_t, bool (const T&, const T&), bool (const T&, const T&, const P)>; ///< Signature of sort function. using FilterFunction = bool(const T*, F); ///< Signature of filter function. diff --git a/src/station_gui.cpp b/src/station_gui.cpp index 32271ce2d0..23e4d6a257 100644 --- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -341,51 +341,51 @@ protected: this->vscroll->SetCount(this->stations.size()); // Update the scrollbar } - /** Sort stations by their name */ - static bool StationNameSorter(const Station * const &a, const Station * const &b, const CargoTypes &) + /** Sort stations by their name. @copydoc GUIList::SorterWithFilter */ + static bool StationNameSorter(const Station * const &a, const Station * const &b, [[maybe_unused]] const CargoTypes &filter) { int r = StrNaturalCompare(a->GetCachedName(), b->GetCachedName()); // Sort by name (natural sorting). if (r == 0) return a->index < b->index; return r < 0; } - /** Sort stations by their type */ - static bool StationTypeSorter(const Station * const &a, const Station * const &b, const CargoTypes &) + /** Sort stations by their type. @copydoc GUIList::SorterWithFilter */ + static bool StationTypeSorter(const Station * const &a, const Station * const &b, [[maybe_unused]] const CargoTypes &filter) { return a->facilities < b->facilities; } - /** Sort stations by their waiting cargo */ - static bool StationWaitingTotalSorter(const Station * const &a, const Station * const &b, const CargoTypes &cargo_filter) + /** Sort stations by their waiting cargo. @copydoc GUIList::SorterWithFilter */ + static bool StationWaitingTotalSorter(const Station * const &a, const Station * const &b, const CargoTypes &filter) { int diff = 0; - for (CargoType cargo : SetCargoBitIterator(cargo_filter)) { + for (CargoType cargo : SetCargoBitIterator(filter)) { diff += a->goods[cargo].TotalCount() - b->goods[cargo].TotalCount(); } return diff < 0; } - /** Sort stations by their available waiting cargo */ - static bool StationWaitingAvailableSorter(const Station * const &a, const Station * const &b, const CargoTypes &cargo_filter) + /** Sort stations by their available waiting cargo. @copydoc GUIList::SorterWithFilter */ + static bool StationWaitingAvailableSorter(const Station * const &a, const Station * const &b, const CargoTypes &filter) { int diff = 0; - for (CargoType cargo : SetCargoBitIterator(cargo_filter)) { + for (CargoType cargo : SetCargoBitIterator(filter)) { diff += a->goods[cargo].AvailableCount() - b->goods[cargo].AvailableCount(); } return diff < 0; } - /** Sort stations by their rating */ - static bool StationRatingMaxSorter(const Station * const &a, const Station * const &b, const CargoTypes &cargo_filter) + /** Sort stations by their rating. @copydoc GUIList::SorterWithFilter */ + static bool StationRatingMaxSorter(const Station * const &a, const Station * const &b, const CargoTypes &filter) { uint8_t maxr1 = 0; uint8_t maxr2 = 0; - for (CargoType cargo : SetCargoBitIterator(cargo_filter)) { + for (CargoType cargo : SetCargoBitIterator(filter)) { if (a->goods[cargo].HasRating()) maxr1 = std::max(maxr1, a->goods[cargo].rating); if (b->goods[cargo].HasRating()) maxr2 = std::max(maxr2, b->goods[cargo].rating); } @@ -393,13 +393,13 @@ protected: return maxr1 < maxr2; } - /** Sort stations by their rating */ - static bool StationRatingMinSorter(const Station * const &a, const Station * const &b, const CargoTypes &cargo_filter) + /** Sort stations by their rating. @copydoc GUIList::SorterWithFilter */ + static bool StationRatingMinSorter(const Station * const &a, const Station * const &b, const CargoTypes &filter) { uint8_t minr1 = 255; uint8_t minr2 = 255; - for (CargoType cargo : SetCargoBitIterator(cargo_filter)) { + for (CargoType cargo : SetCargoBitIterator(filter)) { if (a->goods[cargo].HasRating()) minr1 = std::min(minr1, a->goods[cargo].rating); if (b->goods[cargo].HasRating()) minr2 = std::min(minr2, b->goods[cargo].rating); } diff --git a/src/story_gui.cpp b/src/story_gui.cpp index 65bd5c9db9..c97484a32e 100644 --- a/src/story_gui.cpp +++ b/src/story_gui.cpp @@ -83,7 +83,7 @@ protected: this->story_pages.Sort(); } - /** Sort story pages by order value. */ + /** Sort story pages by order value. @copydoc GUIList::Sorter */ static bool PageOrderSorter(const StoryPage * const &a, const StoryPage * const &b) { return a->sort_value < b->sort_value; @@ -111,7 +111,7 @@ protected: this->InvalidateStoryPageElementLayout(); } - /** Sort story page elements by order value. */ + /** Sort story page elements by order value. @copydoc GUIList::Sorter */ static bool PageElementOrderSorter(const StoryPageElement * const &a, const StoryPageElement * const &b) { return a->sort_value < b->sort_value; diff --git a/src/timetable_cmd.cpp b/src/timetable_cmd.cpp index d6b9900868..c56081ba87 100644 --- a/src/timetable_cmd.cpp +++ b/src/timetable_cmd.cpp @@ -305,10 +305,7 @@ CommandCost CmdSetVehicleOnTime(DoCommandFlags flags, VehicleID veh, bool apply_ /** * Order vehicles based on their timetable. The vehicles will be sorted in order * they would reach the first station. - * - * @param a First Vehicle pointer. - * @param b Second Vehicle pointer. - * @return Comparison value. + * @copydoc GUIList::Sorter */ static bool VehicleTimetableSorter(Vehicle * const &a, Vehicle * const &b) { diff --git a/src/town_gui.cpp b/src/town_gui.cpp index 073a9aaea1..05aab1433e 100644 --- a/src/town_gui.cpp +++ b/src/town_gui.cpp @@ -759,32 +759,32 @@ private: this->SetWidgetDirty(WID_TD_LIST); // Force repaint of the displayed towns. } - /** Sort by town name */ - static bool TownNameSorter(const Town * const &a, const Town * const &b, const bool &) + /** Sort by town name. @copydoc GUIList::SorterWithFilter */ + static bool TownNameSorter(const Town * const &a, const Town * const &b, [[maybe_unused]] const bool &filter) { return StrNaturalCompare(a->GetCachedName(), b->GetCachedName()) < 0; // Sort by name (natural sorting). } - /** Sort by population (default descending, as big towns are of the most interest). */ - static bool TownPopulationSorter(const Town * const &a, const Town * const &b, const bool &order) + /** Sort by population (default descending, as big towns are of the most interest). @copydoc GUIList::SorterWithFilter */ + static bool TownPopulationSorter(const Town * const &a, const Town * const &b, const bool &filter) { uint32_t a_population = a->cache.population; uint32_t b_population = b->cache.population; - if (a_population == b_population) return TownDirectoryWindow::TownNameSorter(a, b, order); + if (a_population == b_population) return TownDirectoryWindow::TownNameSorter(a, b, filter); return a_population < b_population; } - /** Sort by town rating */ - static bool TownRatingSorter(const Town * const &a, const Town * const &b, const bool &order) + /** Sort by town rating. @copydoc GUIList::SorterWithFilter */ + static bool TownRatingSorter(const Town * const &a, const Town * const &b, const bool &filter) { - bool before = !order; // Value to get 'a' before 'b'. + bool before = !filter; // Value to get 'a' before 'b'. /* Towns without rating are always after towns with rating. */ if (a->have_ratings.Test(_local_company)) { if (b->have_ratings.Test(_local_company)) { int16_t a_rating = a->ratings[_local_company]; int16_t b_rating = b->ratings[_local_company]; - if (a_rating == b_rating) return TownDirectoryWindow::TownNameSorter(a, b, order); + if (a_rating == b_rating) return TownDirectoryWindow::TownNameSorter(a, b, filter); return a_rating < b_rating; } return before; @@ -792,8 +792,8 @@ private: if (b->have_ratings.Test(_local_company)) return !before; /* Sort unrated towns always on ascending town name. */ - if (before) return TownDirectoryWindow::TownNameSorter(a, b, order); - return TownDirectoryWindow::TownNameSorter(b, a, order); + if (before) return TownDirectoryWindow::TownNameSorter(a, b, filter); + return TownDirectoryWindow::TownNameSorter(b, a, filter); } public: diff --git a/src/vehicle_gui.cpp b/src/vehicle_gui.cpp index c2d2a77e82..8fcd5d863d 100644 --- a/src/vehicle_gui.cpp +++ b/src/vehicle_gui.cpp @@ -72,7 +72,7 @@ static BaseVehicleListWindow::VehicleGroupSortFunction VehicleGroupTotalProfitLa static BaseVehicleListWindow::VehicleGroupSortFunction VehicleGroupAverageProfitThisYearSorter; static BaseVehicleListWindow::VehicleGroupSortFunction VehicleGroupAverageProfitLastYearSorter; -/** Wrapper to convert a VehicleIndividualSortFunction to a VehicleGroupSortFunction */ +/** Wrapper to convert a VehicleIndividualSortFunction to a VehicleGroupSortFunction. @copydoc GUIList::Sorter */ template static bool VehicleIndividualToGroupSorterWrapper(GUIVehicleGroup const &a, GUIVehicleGroup const &b) { @@ -1401,43 +1401,43 @@ StringID GetCargoSubtypeText(const Vehicle *v) return GetGRFStringID(v->GetGRFID(), GRFSTR_MISC_GRF_TEXT + cb); } -/** Sort vehicle groups by the number of vehicles in the group */ +/** Sort vehicle groups by the number of vehicles in the group. @copydoc GUIList::Sorter */ static bool VehicleGroupLengthSorter(const GUIVehicleGroup &a, const GUIVehicleGroup &b) { return a.NumVehicles() < b.NumVehicles(); } -/** Sort vehicle groups by the total profit this year */ +/** Sort vehicle groups by the total profit this year. @copydoc GUIList::Sorter */ static bool VehicleGroupTotalProfitThisYearSorter(const GUIVehicleGroup &a, const GUIVehicleGroup &b) { return a.GetDisplayProfitThisYear() < b.GetDisplayProfitThisYear(); } -/** Sort vehicle groups by the total profit last year */ +/** Sort vehicle groups by the total profit last year. @copydoc GUIList::Sorter */ static bool VehicleGroupTotalProfitLastYearSorter(const GUIVehicleGroup &a, const GUIVehicleGroup &b) { return a.GetDisplayProfitLastYear() < b.GetDisplayProfitLastYear(); } -/** Sort vehicle groups by the average profit this year */ +/** Sort vehicle groups by the average profit this year. @copydoc GUIList::Sorter */ static bool VehicleGroupAverageProfitThisYearSorter(const GUIVehicleGroup &a, const GUIVehicleGroup &b) { return a.GetDisplayProfitThisYear() * static_cast(b.NumVehicles()) < b.GetDisplayProfitThisYear() * static_cast(a.NumVehicles()); } -/** Sort vehicle groups by the average profit last year */ +/** Sort vehicle groups by the average profit last year. @copydoc GUIList::Sorter */ static bool VehicleGroupAverageProfitLastYearSorter(const GUIVehicleGroup &a, const GUIVehicleGroup &b) { return a.GetDisplayProfitLastYear() * static_cast(b.NumVehicles()) < b.GetDisplayProfitLastYear() * static_cast(a.NumVehicles()); } -/** Sort vehicles by their number */ +/** Sort vehicles by their number. @copydoc GUIList::Sorter */ static bool VehicleNumberSorter(const Vehicle * const &a, const Vehicle * const &b) { return a->unitnumber < b->unitnumber; } -/** Sort vehicles by their name */ +/** Sort vehicles by their name. @copydoc GUIList::Sorter */ static bool VehicleNameSorter(const Vehicle * const &a, const Vehicle * const &b) { static std::string last_name[2] = { {}, {} }; @@ -1456,28 +1456,28 @@ static bool VehicleNameSorter(const Vehicle * const &a, const Vehicle * const &b return (r != 0) ? r < 0: VehicleNumberSorter(a, b); } -/** Sort vehicles by their age */ +/** Sort vehicles by their age. @copydoc GUIList::Sorter */ static bool VehicleAgeSorter(const Vehicle * const &a, const Vehicle * const &b) { auto r = a->age - b->age; return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by this year profit */ +/** Sort vehicles by this year profit. @copydoc GUIList::Sorter */ static bool VehicleProfitThisYearSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = ClampTo(a->GetDisplayProfitThisYear() - b->GetDisplayProfitThisYear()); return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by last year profit */ +/** Sort vehicles by last year profit. @copydoc GUIList::Sorter */ static bool VehicleProfitLastYearSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = ClampTo(a->GetDisplayProfitLastYear() - b->GetDisplayProfitLastYear()); return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by their cargo */ +/** Sort vehicles by their cargo. @copydoc GUIList::Sorter */ static bool VehicleCargoSorter(const Vehicle * const &a, const Vehicle * const &b) { const Vehicle *v; @@ -1496,28 +1496,28 @@ static bool VehicleCargoSorter(const Vehicle * const &a, const Vehicle * const & return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by their reliability */ +/** Sort vehicles by their reliability. @copydoc GUIList::Sorter */ static bool VehicleReliabilitySorter(const Vehicle * const &a, const Vehicle * const &b) { int r = a->reliability - b->reliability; return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by their max speed */ +/** Sort vehicles by their max speed. @copydoc GUIList::Sorter */ static bool VehicleMaxSpeedSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = a->vcache.cached_max_speed - b->vcache.cached_max_speed; return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by model */ +/** Sort vehicles by model. @copydoc GUIList::Sorter */ static bool VehicleModelSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = a->engine_type.base() - b->engine_type.base(); return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by their value */ +/** Sort vehicles by their value. @copydoc GUIList::Sorter */ static bool VehicleValueSorter(const Vehicle * const &a, const Vehicle * const &b) { const Vehicle *u; @@ -1530,21 +1530,21 @@ static bool VehicleValueSorter(const Vehicle * const &a, const Vehicle * const & return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by their length */ +/** Sort vehicles by their length. @copydoc GUIList::Sorter */ static bool VehicleLengthSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = a->GetGroundVehicleCache()->cached_total_length - b->GetGroundVehicleCache()->cached_total_length; return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by the time they can still live */ +/** Sort vehicles by the time they can still live. @copydoc GUIList::Sorter */ static bool VehicleTimeToLiveSorter(const Vehicle * const &a, const Vehicle * const &b) { int r = ClampTo((a->max_age - a->age) - (b->max_age - b->age)); return (r != 0) ? r < 0 : VehicleNumberSorter(a, b); } -/** Sort vehicles by the timetable delay */ +/** Sort vehicles by the timetable delay. @copydoc GUIList::Sorter */ static bool VehicleTimetableDelaySorter(const Vehicle * const &a, const Vehicle * const &b) { int r = a->lateness_counter - b->lateness_counter; diff --git a/src/window.cpp b/src/window.cpp index 3867676bb9..d471275779 100644 --- a/src/window.cpp +++ b/src/window.cpp @@ -162,9 +162,7 @@ void WindowDesc::LoadFromConfig() } } -/** - * Sort WindowDesc by ini_key. - */ +/** Sort WindowDesc by ini_key. @copydoc GUIList::Sorter */ static bool DescSorter(WindowDesc * const &a, WindowDesc * const &b) { return a->ini_key < b->ini_key;