From f2a59e197c1e89c26bd6a5d6b9c87dc84bfcc756 Mon Sep 17 00:00:00 2001 From: alberth Date: Sat, 11 Dec 2010 15:14:28 +0000 Subject: [PATCH] (svn r21467) -Doc: Add a few doxygen comments to config file settings code. --- src/settings.cpp | 21 ++++++++++++++++++--- src/settings_gui.cpp | 27 +++++++++++++++++++++++---- src/settings_internal.h | 1 + 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/src/settings.cpp b/src/settings.cpp index fa64abc733..1834fe72d1 100644 --- a/src/settings.cpp +++ b/src/settings.cpp @@ -72,8 +72,8 @@ #include "table/settings.h" ClientSettings _settings_client; -GameSettings _settings_game; -GameSettings _settings_newgame; +GameSettings _settings_game; ///< Game settings of a running game or the scenario editor. +GameSettings _settings_newgame; ///< Game settings for new games (updated from the intro screen). VehicleDefaultSettings _old_vds; ///< Used for loading default vehicles settings from old savegames char *_config_file; ///< Configuration file of OpenTTD @@ -1237,6 +1237,11 @@ static bool ConvertOldNewsSetting(const char *name, const char *value) return false; } +/** + * Load newstype settings from a configuration file. + * @param ini the configuration to read from. + * @param grpname Name of the group containing the news type settings. + */ static void NewsDisplayLoadConfig(IniFile *ini, const char *grpname) { IniGroup *group = ini->GetGroup(grpname); @@ -1310,7 +1315,12 @@ static void AILoadConfig(IniFile *ini, const char *grpname) #endif /* ENABLE_AI */ } -/* Load a GRF configuration from the given group name */ +/** + * Load a GRF configuration + * @param ini The configuration to read from. + * @param grpname Group name containing the configuration of the GRF. + * @param is_static GRF is static. + */ static GRFConfig *GRFLoadConfig(IniFile *ini, const char *grpname, bool is_static) { IniGroup *group = ini->GetGroup(grpname); @@ -1376,6 +1386,11 @@ static GRFConfig *GRFLoadConfig(IniFile *ini, const char *grpname, bool is_stati return first; } +/** + * Write newstype settings to a configuration file. + * @param ini The configuration to write to. + * @param grpname Name of the group containing the news type settings. + */ static void NewsDisplaySaveConfig(IniFile *ini, const char *grpname) { IniGroup *group = ini->GetGroup(grpname); diff --git a/src/settings_gui.cpp b/src/settings_gui.cpp index f48411e023..0697665200 100644 --- a/src/settings_gui.cpp +++ b/src/settings_gui.cpp @@ -60,6 +60,12 @@ static const StringID _autosave_dropdown[] = { INVALID_STRING_ID, }; +/** + * Fill a static array with consecutive stringIDs for use with a drop down. + * @param base First stringID. + * @param num Number of stringIDs (must be at most 32). + * *return Pointer to the static buffer with stringIDs. + */ static StringID *BuildDynamicDropdown(StringID base, int num) { static StringID buf[32 + 1]; @@ -69,10 +75,11 @@ static StringID *BuildDynamicDropdown(StringID base, int num) return buf; } -int _nb_orig_names = SPECSTR_TOWNNAME_LAST - SPECSTR_TOWNNAME_START + 1; -static StringID *_grf_names = NULL; -static int _nb_grf_names = 0; +int _nb_orig_names = SPECSTR_TOWNNAME_LAST - SPECSTR_TOWNNAME_START + 1; ///< Number of original town names. +static StringID *_grf_names = NULL; ///< Pointer to town names defined by NewGRFs. +static int _nb_grf_names = 0; ///< Number of town names defined by NewGRFs. +/** Allocate memory for the NewGRF town names. */ void InitGRFTownGeneratorNames() { free(_grf_names); @@ -81,6 +88,11 @@ void InitGRFTownGeneratorNames() for (StringID *s = _grf_names; *s != INVALID_STRING_ID; s++) _nb_grf_names++; } +/** + * Get a town name. + * @param town_name Number of the wanted town name. + * @return Name of the town as string ID. + */ static inline StringID TownName(int town_name) { if (town_name < _nb_orig_names) return STR_GAME_OPTIONS_TOWN_NAME_ORIGINAL_ENGLISH + town_name; @@ -89,6 +101,10 @@ static inline StringID TownName(int town_name) return STR_UNDEFINED; } +/** + * Get index of the current screen resolution. + * @return Index of the current screen resolution if it is a known resolution, #_num_resolutions otherwise. + */ static int GetCurRes() { int i; @@ -532,7 +548,7 @@ static const WindowDesc _game_options_desc( _nested_game_options_widgets, lengthof(_nested_game_options_widgets) ); - +/** Open the game options window. */ void ShowGameOptions() { DeleteWindowById(WC_GAME_OPTIONS, 0); @@ -809,6 +825,7 @@ static const WindowDesc _game_difficulty_desc( _nested_game_difficulty_widgets, lengthof(_nested_game_difficulty_widgets) ); +/** Open the game-difficulty window. */ void ShowGameDifficulty() { DeleteWindowById(WC_GAME_OPTIONS, 0); @@ -1719,6 +1736,7 @@ static const WindowDesc _settings_selection_desc( _nested_settings_selection_widgets, lengthof(_nested_settings_selection_widgets) ); +/** Open advanced settings window. */ void ShowGameSettings() { DeleteWindowById(WC_GAME_OPTIONS, 0); @@ -1993,6 +2011,7 @@ static const WindowDesc _cust_currency_desc( _nested_cust_currency_widgets, lengthof(_nested_cust_currency_widgets) ); +/** Open custom currency window. */ static void ShowCustCurrency() { DeleteWindowById(WC_CUSTOM_CURRENCY, 0); diff --git a/src/settings_internal.h b/src/settings_internal.h index 6fe0838960..045d136392 100644 --- a/src/settings_internal.h +++ b/src/settings_internal.h @@ -58,6 +58,7 @@ typedef SimpleTinyEnumT SettingGuiFlag; typedef bool OnChange(int32 var); ///< callback prototype on data modification typedef int32 OnConvert(const char *value); ///< callback prototype for convertion error +/** Properties of config file settings. */ struct SettingDescBase { const char *name; ///< name of the setting. Used in configuration file and for console const void *def; ///< default value given when none is present