From c20c3be91dba2a689cfc5bd7d9673de42d4831ef Mon Sep 17 00:00:00 2001
From: frosch <frosch@openttd.org>
Date: Sun, 28 Sep 2008 15:42:15 +0000
Subject: (svn r14412) -Documentation: Comment some functions related to the
 advanced settings. Patch by Alberth, but with less excessive use of 'at'.

---
 src/settings.cpp     | 16 ++++++++++++++++
 src/settings_gui.cpp | 53 +++++++++++++++++++++++++++++-----------------------
 2 files changed, 46 insertions(+), 23 deletions(-)

(limited to 'src')

diff --git a/src/settings.cpp b/src/settings.cpp
index 263f37404..b49833131 100644
--- a/src/settings.cpp
+++ b/src/settings.cpp
@@ -1941,6 +1941,13 @@ bool SetPatchValue(uint index, const char *value)
 	return true;
 }
 
+/**
+ * Given a name of patch, return a setting description of it.
+ * @param name  Name of the patch to return a setting description of
+ * @param i     Pointer to an integer that will contain the index of the setting after the call, if it is successful.
+ * @return Pointer to the setting description of patch \a name if it can be found,
+ *         \c NULL indicates failure to obtain the description
+ */
 const SettingDesc *GetPatchFromName(const char *name, uint *i)
 {
 	const SettingDesc *sd;
@@ -2003,6 +2010,10 @@ void IConsoleSetPatchSetting(const char *name, int value)
 	SetPatchValue(index, value);
 }
 
+/**
+ * Output value of a specific patch to the console
+ * @param name  Name of the patch to output its value
+ */
 void IConsoleGetPatchSetting(const char *name)
 {
 	char value[20];
@@ -2031,6 +2042,11 @@ void IConsoleGetPatchSetting(const char *name)
 	}
 }
 
+/**
+ * List all patches and their value to the console
+ *
+ * @param prefilter  If not \c NULL, only list patches with names that begin with \a prefilter prefix
+ */
 void IConsoleListPatches(const char *prefilter)
 {
 	IConsolePrintF(CC_WARNING, "All patches with their current value:");
diff --git a/src/settings_gui.cpp b/src/settings_gui.cpp
index 0220bb76b..754a21d16 100644
--- a/src/settings_gui.cpp
+++ b/src/settings_gui.cpp
@@ -708,20 +708,26 @@ static const char *_patches_vehicles[] = {
 	"vehicle.dynamic_engines",
 };
 
+/** Data structure describing a single patch in a tab */
 struct PatchEntry {
-	const SettingDesc *setting;
-	uint index;
+	const SettingDesc *setting; ///< Setting description of the patch
+	uint index;                 ///< Index of the setting in the settings table
 };
 
+/**
+ * Data structure describing one page of patches in the patch settings window.
+ *
+ * The names of the patches to display are statically defined, and from this
+ * information, a dynamic array (with length \a num) of PatchEntry entries is
+ * constructed.
+ */
 struct PatchPage {
-	const char **names;
-	PatchEntry *entries;
-	byte num;
+	const char **names;  ///< Static list of strings with patch names that are settable from the tab
+	PatchEntry *entries; ///< Array of patch entries of the page. Initially \c NULL, filled in at run time
+	byte num;            ///< Number of entries on the page (statically filled).
 };
 
-/* PatchPage holds the categories, the number of elements in each category
- * and (in NULL) a dynamic array of settings based on the string-representations
- * of the settings. This way there is no worry about indeces, and such */
+/** Array of pages (tabs), where each page holds a number of advanced settings. */
 static PatchPage _patches_page[] = {
 	{_patches_ui,           NULL, lengthof(_patches_ui)},
 	{_patches_construction, NULL, lengthof(_patches_construction)},
@@ -731,19 +737,20 @@ static PatchPage _patches_page[] = {
 	{_patches_ai,           NULL, lengthof(_patches_ai)},
 };
 
+/** Widget numbers of config patches window */
 enum PatchesSelectionWidgets {
-	PATCHSEL_OPTIONSPANEL = 3,
-	PATCHSEL_INTERFACE,
-	PATCHSEL_CONSTRUCTION,
-	PATCHSEL_VEHICLES,
-	PATCHSEL_STATIONS,
-	PATCHSEL_ECONOMY,
-	PATCHSEL_COMPETITORS
+	PATCHSEL_OPTIONSPANEL = 3, ///< Panel widget containing the option lists
+	PATCHSEL_INTERFACE,        ///< Button 'Interface'
+	PATCHSEL_CONSTRUCTION,     ///< Button 'Construction'
+	PATCHSEL_VEHICLES,         ///< Button 'Vehicles'
+	PATCHSEL_STATIONS,         ///< Button 'Stations'
+	PATCHSEL_ECONOMY,          ///< Button 'Economy'
+	PATCHSEL_COMPETITORS       ///< Button 'Competitors'
 };
 
 struct PatchesSelectionWindow : Window {
 	static GameSettings *patches_ptr;
-	static int patches_max;
+	static int patches_max;  ///< Maximal number of patches on a single page
 
 	int page;
 	int entry;
@@ -855,15 +862,15 @@ struct PatchesSelectionWindow : Window {
 				int x, y;
 				byte btn;
 
-				y = pt.y - 46 - 1;
-				if (y < 0) return;
+				y = pt.y - 46 - 1;  // Shift y coordinate
+				if (y < 0) return;  // Clicked above first entry
 
-				x = pt.x - 5;
-				if (x < 0) return;
+				x = pt.x - 5;  // Shift x coordinate
+				if (x < 0) return;  // Clicked left of the entry
 
-				btn = y / 11;
-				if (y % 11 > 9) return;
-				if (btn >= page->num) return;
+				btn = y / 11;  // Compute which setting is selected
+				if (y % 11 > 9) return;  // Clicked too low at the setting
+				if (btn >= page->num) return;  // Clicked below the last setting of the page
 
 				sd = page->entries[btn].setting;
 
-- 
cgit v1.2.3-70-g09d2