(svn r21467) -Doc: Add a few doxygen comments to config file settings code.

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);

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);

src/settings_internal.h

@@ -58,6 +58,7 @@ typedef SimpleTinyEnumT<SettingGuiFlagLong, uint16> 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