From 89ffb429c5b5bb7a6ae1a27da86941f672a07e5c Mon Sep 17 00:00:00 2001 From: Rubidium Date: Thu, 19 Feb 2026 18:58:54 +0100 Subject: [PATCH] Codechange: document missing parameters and return values --- src/script/script_config.hpp | 10 ++++++++++ src/script/script_gui.cpp | 3 ++- src/script/script_info.hpp | 22 ++++++++++++++++++++-- src/script/script_info_dummy.cpp | 14 ++++++++++++-- src/script/script_instance.hpp | 13 ++++++++++++- src/script/script_scanner.cpp | 1 + src/settings.cpp | 11 +++++++++++ src/settings_internal.h | 30 ++++++++++++++++++++++++++++++ src/settings_table.cpp | 20 ++++++++++++-------- 9 files changed, 110 insertions(+), 14 deletions(-) diff --git a/src/script/script_config.hpp b/src/script/script_config.hpp index cbe5624b18..3a8cd66dbc 100644 --- a/src/script/script_config.hpp +++ b/src/script/script_config.hpp @@ -88,6 +88,7 @@ public: /** * Get the config list for this ScriptConfig. + * @return The configuration list. */ const ScriptConfigItemList *GetConfigList(); @@ -115,6 +116,7 @@ public: * Get the value of a setting for this config. It might fallback to its * 'info' to find the default value (if not set or if not-custom difficulty * level). + * @param name The name of the setting. * @return The (default) value of the setting, or -1 if the setting was not * found. */ @@ -122,6 +124,8 @@ public: /** * Set the value of a setting for this config. + * @param name The name of the setting. + * @param value The new value for the setting. */ void SetSetting(std::string_view name, int value); @@ -132,34 +136,40 @@ public: /** * Reset only editable and visible settings to their default value. + * @param yet_to_start Denotes whether the script is not yet running, e.g. the main menu. */ void ResetEditableSettings(bool yet_to_start); /** * Is this config attached to an Script? In other words, is there a Script * that is assigned to this slot. + * @return \c true iff a script is assigned to this configuration. */ bool HasScript() const; /** * Get the name of the Script. + * @return The script's name. */ const std::string &GetName() const; /** * Get the version of the Script. + * @return The script's version. */ int GetVersion() const; /** * Convert a string which is stored in the config file or savegames to * custom settings of this Script. + * @param value The string-encoded settings to decode into this configuration. */ void StringToSettings(std::string_view value); /** * Convert the custom settings to a string that can be stored in the config * file or savegames. + * @return The string-encoded version of the settings in this configuration. */ std::string SettingsToString() const; diff --git a/src/script/script_gui.cpp b/src/script/script_gui.cpp index f08215a17b..b5848faefb 100644 --- a/src/script/script_gui.cpp +++ b/src/script/script_gui.cpp @@ -1195,7 +1195,7 @@ struct ScriptDebugWindow : public Window { }, ScriptDebugGlobalHotkeys}; }; -/** Make a number of rows with buttons for each company for the Script debug window. */ +/** Make a number of rows with buttons for each company for the Script debug window. @copydoc NWidgetFunctionType */ std::unique_ptr MakeCompanyButtonRowsScriptDebug() { return MakeCompanyButtonRows(WID_SCRD_COMPANY_BUTTON_START, WID_SCRD_COMPANY_BUTTON_END, COLOUR_GREY, 5, STR_AI_DEBUG_SELECT_AI_TOOLTIP, false); @@ -1262,6 +1262,7 @@ static WindowDesc _script_debug_desc( * Open the Script debug window and select the given company. * @param show_company Display debug information about this AI company. * @param new_window Show in new window instead of existing window. + * @return The existing or allocated window, or \c nullptr when there is no debug window to show. */ Window *ShowScriptDebugWindow(CompanyID show_company, bool new_window) { diff --git a/src/script/script_info.hpp b/src/script/script_info.hpp index f82b5cf53b..0ef6f1238d 100644 --- a/src/script/script_info.hpp +++ b/src/script/script_info.hpp @@ -91,51 +91,69 @@ public: /** * Check if a given method exists. + * @param name The method name to look for. + * @return \c true iff the method exists. */ bool CheckMethod(std::string_view name) const; /** * Process the creation of a FileInfo object. + * @param vm The virtual machine to work on. + * @param info The metadata about the script. + * @return \c 0 upon success, or anything other on failure. */ static SQInteger Constructor(HSQUIRRELVM vm, ScriptInfo &info); /** * Get the scanner which has found this ScriptInfo. + * @return The scanner for scripts. */ virtual class ScriptScanner *GetScanner() { return this->scanner; } /** - * Get the settings of the Script. + * Does this script have a 'GetSettings' function? + * @return \c true iff the script has the GetSettings function. */ bool GetSettings(); /** * Get the config list for this Script. + * @return The configuration list. */ const ScriptConfigItemList *GetConfigList() const; /** * Get the description of a certain Script config option. + * @param name The name of the setting. + * @return The configuration item, or \c nullptr. */ const ScriptConfigItem *GetConfigItem(std::string_view name) const; /** - * Set a setting. + * Add a setting. + * @param vm The virtual machine to work on. + * @return \c 0 upon success, or anything other on failure. */ SQInteger AddSetting(HSQUIRRELVM vm); /** * Add labels for a setting. + * @param vm The virtual machine to work on. + * @return \c 0 upon success, or anything other on failure. */ SQInteger AddLabels(HSQUIRRELVM vm); /** * Get the default value for a setting. + * @param name The name of the setting to get the default for. + * @return The default value for the setting, or \c -1 when the setting does not exist. + * @note \c -1 can be a valid default setting. */ int GetSettingDefaultValue(const std::string &name) const; /** * Can this script be selected by developers only? + * @return \c true iff the script should only be shown to script developers. */ virtual bool IsDeveloperOnly() const { return false; } diff --git a/src/script/script_info_dummy.cpp b/src/script/script_info_dummy.cpp index 101e9bfc62..7b1bfa5c31 100644 --- a/src/script/script_info_dummy.cpp +++ b/src/script/script_info_dummy.cpp @@ -25,7 +25,12 @@ * to select manual. It is a fail-over in case no Scripts are available. */ -/** Run the dummy info.nut. */ +/** + * Run the dummy info.nut. + * @param vm The virtual machine to run in. + * @param type The type of script. + * @param dir The directory where these scripts would normally be in. + */ void Script_CreateDummyInfo(HSQUIRRELVM vm, std::string_view type, std::string_view dir) { std::string dummy_script = fmt::format( @@ -77,7 +82,12 @@ static std::vector EscapeQuotesAndSlashesAndSplitOnNewLines(const s return messages; } -/** Run the dummy AI and let it generate an error message. */ +/** + * Run the dummy AI and let it generate an error message. + * @param vm The virtual machine to run in. + * @param string The error message to show to the end user. + * @param type The type of script. + */ void Script_CreateDummy(HSQUIRRELVM vm, StringID string, std::string_view type) { /* We want to translate the error message. diff --git a/src/script/script_instance.hpp b/src/script/script_instance.hpp index b5b6f3b91d..b51209be17 100644 --- a/src/script/script_instance.hpp +++ b/src/script/script_instance.hpp @@ -45,6 +45,7 @@ public: /** * Create a new script. + * @param api_name The name of the API (AI/GS). */ ScriptInstance(std::string_view api_name); virtual ~ScriptInstance(); @@ -90,11 +91,13 @@ public: /** * Get the storage of this script. + * @return The storage associated with this script. */ class ScriptStorage &GetStorage(); /** * Get the log pointer of this script. + * @return The logs associated with this script. */ ScriptLogTypes::LogData &GetLogData(); @@ -154,6 +157,7 @@ public: /** * Get the controller attached to the instance. + * @return The instance's controller. */ class ScriptController &GetController() { @@ -162,12 +166,14 @@ public: } /** - * Return the "this script died" value + * Return the "this script died" value. + * @return \c true iff the script is dead. */ inline bool IsDead() const { return this->is_dead; } /** * Return whether the script is alive. + * @return \c true iff the script not dead and not dying (being shut down). */ inline bool IsAlive() const { return !this->IsDead() && !this->in_shutdown; } @@ -247,6 +253,7 @@ public: * Check if the instance is sleeping, which either happened because the * script executed a DoCommand, executed this.Sleep() or it has been * paused. + * @return \c true iff the script is sleeping or paused. */ bool IsSleeping() { return this->suspend != 0; } @@ -254,6 +261,7 @@ public: /** * Indicate whether this instance is currently being destroyed. + * @return \c true iff being shut down. */ inline bool InShutdown() const { return this->in_shutdown; } @@ -287,6 +295,7 @@ protected: /** * Get the callback handling DoCommands in case of networking. + * @return The callback function to use to get results back to the script. */ virtual CommandCallbackData *GetDoCommandCallback() = 0; @@ -312,6 +321,7 @@ private: /** * Call the script Load function if it exists and data was loaded * from a savegame. + * @return \c true iff the load succeeded. */ bool CallLoad(); @@ -337,6 +347,7 @@ private: /** * Load all objects from a savegame. + * @param data The data from the savegame. * @return True if the loading was successful. */ static bool LoadObjects(ScriptData *data); diff --git a/src/script/script_scanner.cpp b/src/script/script_scanner.cpp index ca092878f4..83774e28aa 100644 --- a/src/script/script_scanner.cpp +++ b/src/script/script_scanner.cpp @@ -147,6 +147,7 @@ struct ScriptFileChecksumCreator : FileScanner { /** * Initialise the md5sum to be all zeroes, * so we can easily xor the data. + * @param dir The directory to look in. */ ScriptFileChecksumCreator(Subdirectory dir) : dir(dir) {} diff --git a/src/settings.cpp b/src/settings.cpp index 01f291b148..58bc1ab8bb 100644 --- a/src/settings.cpp +++ b/src/settings.cpp @@ -77,6 +77,7 @@ static ErrorList _settings_error_list; ///< Errors while loading minimal setting * - _company_settings * - _win32_settings * As such, they are not part of this list. + * @return The list of generic settings. */ static auto &GenericSettingTables() { @@ -99,6 +100,7 @@ static auto &GenericSettingTables() /** * List of all the private setting tables. + * @return The list of private settings. */ static auto &PrivateSettingTables() { @@ -110,6 +112,7 @@ static auto &PrivateSettingTables() /** * List of all the secrets setting tables. + * @return The list of secret settings. */ static auto &SecretSettingTables() { @@ -438,6 +441,7 @@ StringID IntSettingDesc::GetHelp() const /** * Get parameters for drawing the value of the setting. * @param value Setting value to set params for. + * @return The string parameters for formatting the value of this setting. */ std::pair IntSettingDesc::GetValueParams(int32_t value) const { @@ -1000,6 +1004,7 @@ static void GameLoadConfig(const IniFile &ini, std::string_view grpname) /** * Load BaseGraphics set selection and configuration. + * @param ini The ini-file to read from. */ static void GraphicsSetLoadConfig(IniFile &ini) { @@ -1052,6 +1057,7 @@ static void GraphicsSetLoadConfig(IniFile &ini) * @param ini The configuration to read from. * @param grpname Group name containing the configuration of the GRF. * @param is_static GRF is static. + * @return The list of loaded NewGRF configurations. */ static GRFConfigList GRFLoadConfig(const IniFile &ini, std::string_view grpname, bool is_static) { @@ -1226,6 +1232,7 @@ static void SaveVersionInConfig(IniFile &ini) /** * Save BaseGraphics set selection and configuration. + * @param ini The ini-file to write to. */ static void GraphicsSetSaveConfig(IniFile &ini) { @@ -1671,6 +1678,7 @@ void GetSaveLoadFromSettingTable(SettingTable settings, std::vector &s /** * Create a single table with all settings that should be stored/loaded * in the savegame. + * @return The settings that are in save games. */ SettingTable GetSaveLoadSettingTable() { @@ -1810,6 +1818,7 @@ CommandCost CmdChangeCompanySetting(DoCommandFlags flags, const std::string &nam * @param sd The SettingDesc we want to change. * @param value new value of the setting * @param force_newgame force the newgame settings + * @return \c true iff the setting was changed. */ bool SetSettingValue(const IntSettingDesc *sd, int32_t value, bool force_newgame) { @@ -1849,6 +1858,7 @@ bool SetSettingValue(const IntSettingDesc *sd, int32_t value, bool force_newgame /** * Set the company settings for a new company to their default values. + * @param cid The company to reset the settings for. */ void SetDefaultCompanySettings(CompanyID cid) { @@ -1885,6 +1895,7 @@ void SyncCompanySettings() * @param sd the setting to change. * @param value the value to write * @param force_newgame force the newgame settings + * @return \c true iff the setting was changed. * @note Strings WILL NOT be synced over the network */ bool SetSettingValue(const StringSettingDesc *sd, std::string_view value, bool force_newgame) diff --git a/src/settings_internal.h b/src/settings_internal.h index 828d272c88..ee59999752 100644 --- a/src/settings_internal.h +++ b/src/settings_internal.h @@ -156,10 +156,40 @@ struct SettingDesc { /** Base integer type, including boolean, settings. Only these are shown in the settings UI. */ struct IntSettingDesc : SettingDesc { + /** + * Callback to get the title for the settings panel of this setting. + * @param sd The setting to consider. + * @return The StringID of the title. + */ using GetTitleCallback = StringID(const IntSettingDesc &sd); + + /** + * Callback to get the help description for the settings panel of this setting. + * @param sd The setting to consider. + * @return The StringID of the help. + */ using GetHelpCallback = StringID(const IntSettingDesc &sd); + + /** + * Callback to parameters for string formatting for this setting. + * @param sd The setting to consider. + * @param value The value of the setting. + * @return The string parameters. + */ using GetValueParamsCallback = std::pair(const IntSettingDesc &sd, int32_t value); + + /** + * Callback to get default value for this setting. + * @param sd The setting to consider. + * @return The default value. + */ using GetDefaultValueCallback = int32_t(const IntSettingDesc &sd); + + /** + * Callback to get range of valid values for this setting. + * @param sd The setting to consider. + * @return The range, start and end are included.. + */ using GetRangeCallback = std::tuple(const IntSettingDesc &sd); /** diff --git a/src/settings_table.cpp b/src/settings_table.cpp index abda98f7cf..b634946200 100644 --- a/src/settings_table.cpp +++ b/src/settings_table.cpp @@ -82,20 +82,20 @@ SettingTable _win32_settings{ _win32_settings_table }; /* Begin - Callback Functions for the various settings. */ -/** Switch setting title depending on wallclock setting */ +/** Switch setting title depending on wallclock setting. @copydoc IntSettingDesc::GetTitleCallback */ static StringID SettingTitleWallclock(const IntSettingDesc &sd) { return TimerGameEconomy::UsingWallclockUnits(_game_mode == GM_MENU) ? sd.str + 1 : sd.str; } -/** Switch setting help depending on wallclock setting */ +/** Switch setting help depending on wallclock setting. @copydoc IntSettingDesc::GetHelpCallback */ static StringID SettingHelpWallclock(const IntSettingDesc &sd) { return TimerGameEconomy::UsingWallclockUnits(_game_mode == GM_MENU) ? sd.str_help + 1 : sd.str_help; } -/** Setting values for velocity unit localisation */ -static std::pair SettingsValueVelocityUnit(const IntSettingDesc &, int32_t value) +/** Setting values for velocity unit localisation. @copydoc IntSettingDesc::GetValueParamsCallback */ +static std::pair SettingsValueVelocityUnit([[maybe_unused]] const IntSettingDesc &sd, int32_t value) { StringID val; switch (value) { @@ -109,14 +109,14 @@ static std::pair SettingsValueVelocityUnit(con return {val, {}}; } -/** A negative value has another string (the one after "strval"). */ +/** A negative value has another string (the one after "strval"). @copydoc IntSettingDesc::GetValueParamsCallback */ static std::pair SettingsValueAbsolute(const IntSettingDesc &sd, int32_t value) { return {sd.str_val + ((value >= 0) ? 1 : 0), abs(value)}; } -/** Service Interval Settings Default Value displays the correct units or as a percentage */ -static std::pair ServiceIntervalSettingsValueText(const IntSettingDesc &sd, int32_t value) +/** Service Interval Settings Default Value displays the correct units or as a percentage. @copydoc IntSettingDesc::GetValueParamsCallback */ +static std::pair ServiceIntervalSettingsValueText(const IntSettingDesc &sd, int32_t value) { VehicleDefaultSettings *vds; if (_game_mode == GM_MENU || !Company::IsValidID(_current_company)) { @@ -264,6 +264,9 @@ static void UpdateServiceInterval(VehicleType type, int32_t new_value) /** * Checks if the service intervals in the settings are specified as percentages and corrects the default value accordingly. + * @param sd The current setting. + * @param type The vehicle's type. + * @return The appropriate service interval. */ static int32_t GetDefaultServiceInterval(const IntSettingDesc &sd, VehicleType type) { @@ -520,8 +523,9 @@ static void UpdateFreeformEdges(int32_t new_value) /** * Changing the setting "allow multiple NewGRF sets" is not allowed * if there are vehicles. + * @copydoc IntSettingDesc::PreChangeCheck */ -static bool CheckDynamicEngines(int32_t &) +static bool CheckDynamicEngines([[maybe_unused]] int32_t &value) { if (_game_mode == GM_MENU) return true;