From a39a446e8faf99568eb8924535fd0034db00bb8e Mon Sep 17 00:00:00 2001 From: smatz Date: Mon, 18 Jan 2010 14:58:32 +0000 Subject: (svn r18861) -Doc: more doxygen documentation in genworld files --- src/genworld.cpp | 20 +++++++---- src/genworld.h | 16 +++++---- src/genworld_gui.cpp | 100 +++++++++++++++++++++++++++------------------------ 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), -- cgit v1.2.3-70-g09d2