(svn r18861) -Doc: more doxygen documentation in genworld files

3 files changed, 75 insertions, 61 deletions

diff --git a/src/genworld.cpp b/src/genworld.cpp
index 9f479210b..973bf89ff 100644
--- a/src/genworld.cpp
+++ b/src/genworld.cpp
@@ -48,10 +48,12 @@ void StartupDisasters();
 
 void InitializeGame(uint size_x, uint size_y, bool reset_date, bool reset_settings);
 
-/* Please only use this variable in genworld.h and genworld.cpp and
+/**
+ * Please only use this variable in genworld.h and genworld.cpp and
  *  nowhere else. For speed improvements we need it to be global, but
  *  in no way the meaning of it is to use it anywhere else besides
- *  in the genworld.h and genworld.cpp! -- TrueLight */
+ *  in the genworld.h and genworld.cpp! -- TrueLight
+ */
 GenWorldInfo _gw;
 
 /** Rights for the map generation */
@@ -61,6 +63,7 @@ ThreadMutex *_genworld_paint_mutex = ThreadMutex::New();
 
 /**
  * Tells if the world generation is done in a thread or not.
+ * @return the 'threaded' status
  */
 bool IsGenerateWorldThreaded()
 {
@@ -91,7 +94,7 @@ static void CleanupGeneration()
 /**
  * The internal, real, generate function.
  */
-static void _GenerateWorld(void *arg)
+static void _GenerateWorld(void *)
 {
 	try {
 		_generating_world = true;
@@ -190,7 +193,8 @@ static void _GenerateWorld(void *arg)
 
 /**
  * Set here the function, if any, that you want to be called when landscape
- *  generation is done.
+ * generation is done.
+ * @param proc callback procedure
  */
 void GenerateWorldSetCallback(GWDoneProc *proc)
 {
@@ -199,7 +203,8 @@ void GenerateWorldSetCallback(GWDoneProc *proc)
 
 /**
  * Set here the function, if any, that you want to be called when landscape
- *  generation is aborted.
+ * generation is aborted.
+ * @param proc callback procedure
  */
 void GenerateWorldSetAbortCallback(GWAbortProc *proc)
 {
@@ -208,7 +213,7 @@ void GenerateWorldSetAbortCallback(GWAbortProc *proc)
 
 /**
  * This will wait for the thread to finish up his work. It will not continue
- *  till the work is done.
+ * till the work is done.
  */
 void WaitTillGeneratedWorld()
 {
@@ -235,6 +240,7 @@ void AbortGeneratingWorld()
 
 /**
  * Is the generation being aborted?
+ * @return the 'aborted' status
  */
 bool IsGeneratingWorldAborted()
 {
@@ -261,7 +267,7 @@ void HandleGeneratingWorldAbortion()
 
 /**
  * Generate a world.
- * @param mode The mode of world generation (see GenerateWorldModes).
+ * @param mode The mode of world generation (see GenWorldMode).
  * @param size_x The X-size of the map.
  * @param size_y The Y-size of the map.
  * @param reset_settings Whether to reset the game configuration (used for restart)
diff --git a/src/genworld.h b/src/genworld.h
index 591f6ef61..a4399097e 100644
--- a/src/genworld.h
+++ b/src/genworld.h
@@ -14,11 +14,10 @@
 
 #include "company_type.h"
 
-/*
- * Order of these enums has to be the same as in lang/english.txt
- * Otherwise you will get inconsistent behaviour.
- */
+/** Constants related to world generation */
 enum {
+	/* Order of these enums has to be the same as in lang/english.txt
+	 * Otherwise you will get inconsistent behaviour. */
 	LG_ORIGINAL     = 0,  ///< The original landscape generator
 	LG_TERRAGENESIS = 1,  ///< TerraGenesis Perlin landscape generator
 
@@ -27,7 +26,7 @@ enum {
 	GENWORLD_REDRAW_TIMEOUT = 200, ///< Timeout between redraws
 };
 
-/* Modes for GenerateWorld */
+/** Modes for GenerateWorld */
 enum GenWorldMode {
 	GWM_NEWGAME   = 0, ///< Generate a map for a new game
 	GWM_EMPTY     = 1, ///< Generate an empty map (sea-level)
@@ -35,9 +34,10 @@ enum GenWorldMode {
 	GWM_HEIGHTMAP = 3, ///< Generate a newgame from a heightmap
 };
 
-typedef void GWDoneProc();
-typedef void GWAbortProc();
+typedef void GWDoneProc();  ///< Procedure called when the genworld process finishes
+typedef void GWAbortProc(); ///< Called when genworld is aborted
 
+/** Properties of current genworld process */
 struct GenWorldInfo {
 	bool active;           ///< Is generating world active
 	bool abort;            ///< Whether to abort the thread ASAP
@@ -52,6 +52,7 @@ struct GenWorldInfo {
 	class ThreadObject *thread; ///< The thread we are in (can be NULL)
 };
 
+/** Current stage of world generation process */
 enum GenWorldProgress {
 	GWP_MAP_INIT,    ///< Initialize/allocate the map, start economy
 	GWP_LANDSCAPE,   ///< Create the landscape
@@ -68,6 +69,7 @@ enum GenWorldProgress {
 
 /**
  * Check if we are currently in the process of generating a world.
+ * @return are we generating world?
  */
 static inline bool IsGeneratingWorld()
 {
diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp
index 970c34add..c5432bcd1 100644
--- a/src/genworld_gui.cpp
+++ b/src/genworld_gui.cpp
@@ -40,15 +40,18 @@
  * In what 'mode' the GenerateLandscapeWindowProc is.
  */
 enum GenenerateLandscapeWindowMode {
-	GLWM_GENERATE,
-	GLWM_HEIGHTMAP,
-	GLWM_SCENARIO,
-	GLWM_END
+	GLWM_GENERATE,  ///< Generate new game
+	GLWM_HEIGHTMAP, ///< Load from heightmap
+	GLWM_SCENARIO,  ///< Generate flat land
 };
 
 extern void SwitchToMode(SwitchMode new_mode);
 extern void MakeNewgameSettingsLive();
 
+/**
+ * Changes landscape type and sets genworld window dirty
+ * @param landscape new landscape type
+ */
 static inline void SetNewLandscapeType(byte landscape)
 {
 	_settings_newgame.game_creation.landscape = landscape;
@@ -56,51 +59,53 @@ static inline void SetNewLandscapeType(byte landscape)
 	SetWindowClassesDirty(WC_GENERATE_LANDSCAPE);
 }
 
+/** Widgets of GenerateLandscapeWindow */
 enum GenerateLandscapeWindowWidgets {
-	GLAND_TEMPERATE,
-	GLAND_ARCTIC,
-	GLAND_TROPICAL,
-	GLAND_TOYLAND,
-
-	GLAND_MAPSIZE_X_PULLDOWN,
-	GLAND_MAPSIZE_Y_PULLDOWN,
-
-	GLAND_TOWN_PULLDOWN,
-	GLAND_INDUSTRY_PULLDOWN,
-
-	GLAND_RANDOM_EDITBOX,
-	GLAND_RANDOM_BUTTON,
-
-	GLAND_GENERATE_BUTTON,
-
-	GLAND_START_DATE_DOWN,
-	GLAND_START_DATE_TEXT,
-	GLAND_START_DATE_UP,
-
-	GLAND_SNOW_LEVEL_DOWN,
-	GLAND_SNOW_LEVEL_TEXT,
-	GLAND_SNOW_LEVEL_UP,
-
-	GLAND_TREE_PULLDOWN,
-	GLAND_LANDSCAPE_PULLDOWN,
-	GLAND_HEIGHTMAP_NAME_TEXT,
-	GLAND_HEIGHTMAP_NAME_SPACER,
-	GLAND_HEIGHTMAP_SIZE_TEXT,
-	GLAND_HEIGHTMAP_ROTATION_PULLDOWN,
-
-	GLAND_TERRAIN_PULLDOWN,
-	GLAND_WATER_PULLDOWN,
-	GLAND_SMOOTHNESS_PULLDOWN,
-	GLAND_VARIETY_PULLDOWN,
-
-	GLAND_BORDER_TYPES,
-	GLAND_BORDERS_RANDOM,
-	GLAND_WATER_NW,
-	GLAND_WATER_NE,
-	GLAND_WATER_SE,
-	GLAND_WATER_SW,
+	GLAND_TEMPERATE,          ///< Button with icon "Temperate"
+	GLAND_ARCTIC,             ///< Button with icon "Arctic"
+	GLAND_TROPICAL,           ///< Button with icon "Tropical"
+	GLAND_TOYLAND,            ///< Button with icon "Toyland"
+
+	GLAND_MAPSIZE_X_PULLDOWN, ///< Dropdown 'map X size'
+	GLAND_MAPSIZE_Y_PULLDOWN, ///< Dropdown 'map Y size'
+
+	GLAND_TOWN_PULLDOWN,      ///< Dropdown 'No. of towns'
+	GLAND_INDUSTRY_PULLDOWN,  ///< Dropdown 'No. of industries'
+
+	GLAND_RANDOM_EDITBOX,     ///< 'Random seed' editbox
+	GLAND_RANDOM_BUTTON,      ///< 'Randomise' button
+
+	GLAND_GENERATE_BUTTON,    ///< 'Generate' button
+
+	GLAND_START_DATE_DOWN,    ///< Decrease start year
+	GLAND_START_DATE_TEXT,    ///< Start year
+	GLAND_START_DATE_UP,      ///< Increase start year
+
+	GLAND_SNOW_LEVEL_DOWN,    ///< Docrease snow level
+	GLAND_SNOW_LEVEL_TEXT,    ///< Snow level
+	GLAND_SNOW_LEVEL_UP,      ///< Increase snow level
+
+	GLAND_TREE_PULLDOWN,      ///< Dropdown 'Tree algorithm'
+	GLAND_LANDSCAPE_PULLDOWN, ///< Dropdown 'Land generator'
+
+	GLAND_HEIGHTMAP_NAME_TEXT,         ///< Heightmap name
+	GLAND_HEIGHTMAP_NAME_SPACER,       ///< Spacer used for aligning items in the second column nicely
+	GLAND_HEIGHTMAP_SIZE_TEXT,         ///< Size of heightmap
+	GLAND_HEIGHTMAP_ROTATION_PULLDOWN, ///< Dropdown 'Heightmap rotation'
+
+	GLAND_TERRAIN_PULLDOWN,    ///< Dropdown 'Terrain type'
+	GLAND_WATER_PULLDOWN,      ///< Dropdown 'Sea level'
+	GLAND_SMOOTHNESS_PULLDOWN, ///< Dropdown 'Smoothness'
+	GLAND_VARIETY_PULLDOWN,    ///< Dropdown 'Variety distribution'
+
+	GLAND_BORDERS_RANDOM,      ///< 'Random'/'Manual' borders
+	GLAND_WATER_NW,            ///< NW 'Water'/'Freeform'
+	GLAND_WATER_NE,            ///< NE 'Water'/'Freeform'
+	GLAND_WATER_SE,            ///< SE 'Water'/'Freeform'
+	GLAND_WATER_SW,            ///< SW 'Water'/'Freeform'
 };
 
+/** Widgets of GenerateLandscapeWindow when generating world */
 static const NWidgetPart _nested_generate_landscape_widgets[] = {
 	NWidget(NWID_HORIZONTAL),
 		NWidget(WWT_CLOSEBOX, COLOUR_BROWN),
@@ -133,7 +138,7 @@ static const NWidgetPart _nested_generate_landscape_widgets[] = {
 					NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_QUANTITY_OF_SEA_LAKES, STR_NULL), SetFill(1, 1),
 					NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_TREE_PLACER, STR_NULL), SetFill(1, 1),
 					NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_VARIETY, STR_NULL), SetFill(1, 1),
-					NWidget(WWT_TEXT, COLOUR_ORANGE, GLAND_BORDER_TYPES), SetDataTip(STR_MAPGEN_BORDER_TYPE, STR_NULL), SetFill(1, 1),
+					NWidget(WWT_TEXT, COLOUR_ORANGE), SetDataTip(STR_MAPGEN_BORDER_TYPE, STR_NULL), SetFill(1, 1),
 				EndContainer(),
 				/* Widgets at the right of the labels. */
 				NWidget(NWID_VERTICAL, NC_EQUALSIZE), SetPIP(0, 4, 0),
@@ -213,6 +218,7 @@ static const NWidgetPart _nested_generate_landscape_widgets[] = {
 	EndContainer(),
 };
 
+/** Widgets of GenerateLandscapeWindow when loading heightmap */
 static const NWidgetPart _nested_heightmap_load_widgets[] = {
 	/* Window header. */
 	NWidget(NWID_HORIZONTAL),