(svn r22080) -Doc: Add doxygen comments to a few functions and improve a few existing comments

7 files changed, 113 insertions, 8 deletions

diff --git a/readme.txt b/readme.txt
index 0ad799c4d..9c31e6003 100644
--- a/readme.txt
+++ b/readme.txt
@@ -534,9 +534,9 @@ look at http://wiki.openttd.org/index.php/Command_line.
 The most frequent problem is missing data files. Please install OpenGFX and
 possibly OpenSFX and OpenMSX. See section 4.1.1 for more information.
 
-Under, especially, Ubuntu OpenTTD can be extremely slow and freeze/hand under
-certain circumstance. See known-bugs.txt for more information and how to
-solve this problem on your computer.
+Under certain circumstance, especially on Ubuntu OpenTTD can be extremely slow
+and/or freeze. See known-bugs.txt for more information and how to solve this
+problem on your computer.
 
 Under Windows 98 and lower it is impossible to use a dedicated server; it will
 fail to start. Perhaps this is for the better because those OSes are not known
diff --git a/src/company_base.h b/src/company_base.h
index 6078c8b53..de1bbeb1b 100644
--- a/src/company_base.h
+++ b/src/company_base.h
@@ -53,7 +53,7 @@ struct CompanyProperties {
 
 	RailTypes avail_railtypes;       ///< Rail types available to the company.
 
-	byte block_preview;              ///< Number of months that the company is not allowed to get new exclusive engine previews.
+	byte block_preview;              ///< Number of quarters that the company is not allowed to get new exclusive engine previews (see CompaniesGenStatistics).
 
 	uint32 cargo_types;              ///< Which cargo types were transported the last year.
 
diff --git a/src/console_cmds.cpp b/src/console_cmds.cpp
index 7cd18bd6e..539a58663 100644
--- a/src/console_cmds.cpp
+++ b/src/console_cmds.cpp
@@ -56,6 +56,10 @@ static bool _script_running; ///< Script is running (used to abort execution whe
 
 #ifdef ENABLE_NETWORK
 
+/**
+ * Check network availability and inform in console about failure of detection.
+ * @return Network availability.
+ */
 static inline bool NetworkAvailable(bool echo)
 {
 	if (!_network_available) {
@@ -65,6 +69,10 @@ static inline bool NetworkAvailable(bool echo)
 	return true;
 }
 
+/**
+ * Check whether we are a server.
+ * @return Are we a server? True when yes, false otherwise.
+ */
 DEF_CONSOLE_HOOK(ConHookServerOnly)
 {
 	if (!NetworkAvailable(echo)) return CHR_DISALLOW;
@@ -76,6 +84,10 @@ DEF_CONSOLE_HOOK(ConHookServerOnly)
 	return CHR_ALLOW;
 }
 
+/**
+ * Check whether we are a client in a network game.
+ * @return Are we a client in a network game? True when yes, false otherwise.
+ */
 DEF_CONSOLE_HOOK(ConHookClientOnly)
 {
 	if (!NetworkAvailable(echo)) return CHR_DISALLOW;
@@ -87,6 +99,10 @@ DEF_CONSOLE_HOOK(ConHookClientOnly)
 	return CHR_ALLOW;
 }
 
+/**
+ * Check whether we are in a multiplayer game.
+ * @return True when we are client or server in a network game.
+ */
 DEF_CONSOLE_HOOK(ConHookNeedNetwork)
 {
 	if (!NetworkAvailable(echo)) return CHR_DISALLOW;
@@ -98,6 +114,10 @@ DEF_CONSOLE_HOOK(ConHookNeedNetwork)
 	return CHR_ALLOW;
 }
 
+/**
+ * Check whether we are in single player mode.
+ * @return True when no network is active.
+ */
 DEF_CONSOLE_HOOK(ConHookNoNetwork)
 {
 	if (_networking) {
@@ -127,11 +147,19 @@ DEF_CONSOLE_HOOK(ConHookNewGRFDeveloperTool)
 	return CHR_HIDE;
 }
 
+/**
+ * Show help for the console.
+ * @param str String to print in the console.
+ */
 static void IConsoleHelp(const char *str)
 {
 	IConsolePrintF(CC_WARNING, "- %s", str);
 }
 
+/**
+ * Reset status of all engines.
+ * @return Will always succeed.
+ */
 DEF_CONSOLE_CMD(ConResetEngines)
 {
 	if (argc == 0) {
@@ -143,6 +171,11 @@ DEF_CONSOLE_CMD(ConResetEngines)
 	return true;
 }
 
+/**
+ * Reset status of the engine pool.
+ * @return Will always return true.
+ * @note Resetting the pool only succeeds when there are no vehicles ingame.
+ */
 DEF_CONSOLE_CMD(ConResetEnginePool)
 {
 	if (argc == 0) {
@@ -164,6 +197,11 @@ DEF_CONSOLE_CMD(ConResetEnginePool)
 }
 
 #ifdef _DEBUG
+/**
+ * Reset a tile to bare land in debug mode.
+ * param tile number.
+ * @return True when the tile is reset or the help on usage was printed (0 or two parameters).
+ */
 DEF_CONSOLE_CMD(ConResetTile)
 {
 	if (argc == 0) {
@@ -184,6 +222,15 @@ DEF_CONSOLE_CMD(ConResetTile)
 }
 #endif /* _DEBUG */
 
+/**
+ * Scroll to a tile on the map.
+ * @param arg1 tile tile number or tile x coordinate.
+ * @param arg2 optionally tile y coordinate.
+ * @note When only one argument is given it is intepreted as the tile number.
+ *       When two arguments are given, they are interpreted as the tile's x
+ *       and y coordinates.
+ * @return True when either console help was shown or a proper amount of parameters given.
+ */
 DEF_CONSOLE_CMD(ConScrollToTile)
 {
 	switch (argc) {
@@ -223,7 +270,11 @@ DEF_CONSOLE_CMD(ConScrollToTile)
 	return false;
 }
 
-/* Save the map to a file */
+/**
+ * Save the map to a file.
+ * @param filename the filename to save the map to.
+ * @return True when help was displayed or the file attempted to be saved.
+ */
 DEF_CONSOLE_CMD(ConSave)
 {
 	if (argc == 0) {
@@ -247,7 +298,10 @@ DEF_CONSOLE_CMD(ConSave)
 	return false;
 }
 
-/* Explicitly save the configuration */
+/**
+ * Explicitly save the configuration.
+ * @return True.
+ */
 DEF_CONSOLE_CMD(ConSaveConfig)
 {
 	if (argc == 0) {
@@ -261,6 +315,12 @@ DEF_CONSOLE_CMD(ConSaveConfig)
 	return true;
 }
 
+/**
+ * Get savegame file informations.
+ * @param file The savegame filename to return information about. Can be the actual name
+ *             or a numbered entry into the filename list.
+ * @return FiosItem The information on the file.
+ */
 static const FiosItem *GetFiosItem(const char *file)
 {
 	_saveload_mode = SLD_LOAD_GAME;
diff --git a/src/economy.cpp b/src/economy.cpp
index 3d2a419ee..584eea7c7 100644
--- a/src/economy.cpp
+++ b/src/economy.cpp
@@ -552,6 +552,7 @@ static void CompaniesGenStatistics()
 	}
 	cur_company.Restore();
 
+	/* Only run the economic statics and update company stats every 3rd month (1st of quarter). */
 	if (!HasBit(1 << 0 | 1 << 3 | 1 << 6 | 1 << 9, _cur_month)) return;
 
 	Company *c;
diff --git a/src/misc_gui.cpp b/src/misc_gui.cpp
index e30d9c2e8..33c22ed7a 100644
--- a/src/misc_gui.cpp
+++ b/src/misc_gui.cpp
@@ -331,6 +331,10 @@ public:
 	}
 };
 
+/**
+ * Show land information window.
+ * @param tile The tile to show information about.
+ */
 void ShowLandInfo(TileIndex tile)
 {
 	DeleteWindowById(WC_LAND_INFO, 0);
@@ -704,7 +708,7 @@ public:
  * Display an error message in a window.
  * @param summary_msg  General error message showed in first line. Must be valid.
  * @param detailed_msg Detailed error message showed in second line. Can be INVALID_STRING_ID.
- * @param wl           Message severity
+ * @param wl           Message severity.
  * @param x            World X position (TileVirtX) of the error location. Set both x and y to 0 to just center the message when there is no related error tile.
  * @param y            World Y position (TileVirtY) of the error location. Set both x and y to 0 to just center the message when there is no related error tile.
  */
@@ -736,6 +740,12 @@ void ShowErrorMessage(StringID summary_msg, StringID detailed_msg, WarningLevel
 	new ErrmsgWindow(pt, summary_msg, detailed_msg, no_timeout);
 }
 
+/**
+ * Display estimated costs.
+ * @param cost Estimated cost (or income if negative).
+ * @param x    X position of the notification window.
+ * @param y    Y position of the notification window.
+ */
 void ShowEstimatedCostOrIncome(Money cost, int x, int y)
 {
 	StringID msg = STR_MESSAGE_ESTIMATED_COST;
@@ -748,6 +758,13 @@ void ShowEstimatedCostOrIncome(Money cost, int x, int y)
 	ShowErrorMessage(msg, INVALID_STRING_ID, WL_INFO, x, y);
 }
 
+/**
+ * Display animated income or costs on the map.
+ * @param x    World X position of the animation location.
+ * @param y    World Y position of the animation location.
+ * @param z    World Z position of the animation location.
+ * @param cost Estimated cost (or income if negative).
+ */
 void ShowCostOrIncomeAnimation(int x, int y, int z, Money cost)
 {
 	Point pt = RemapCoords(x, y, z);
@@ -761,6 +778,13 @@ void ShowCostOrIncomeAnimation(int x, int y, int z, Money cost)
 	AddTextEffect(msg, pt.x, pt.y, DAY_TICKS, TE_RISING);
 }
 
+/**
+ * Display animated feeder income.
+ * @param x    World X position of the animation location.
+ * @param y    World Y position of the animation location.
+ * @param z    World Z position of the animation location.
+ * @param cost Estimated feeder income.
+ */
 void ShowFeederIncomeAnimation(int x, int y, int z, Money cost)
 {
 	Point pt = RemapCoords(x, y, z);
@@ -769,6 +793,15 @@ void ShowFeederIncomeAnimation(int x, int y, int z, Money cost)
 	AddTextEffect(STR_FEEDER, pt.x, pt.y, DAY_TICKS, TE_RISING);
 }
 
+/**
+ * Display vehicle loading indicators.
+ * @param x       World X position of the animation location.
+ * @param y       World Y position of the animation location.
+ * @param z       World Z position of the animation location.
+ * @param percent Estimated feeder income.
+ * @param string  String which is drawn on the map.
+ * @return        TextEffectID to be used for future updates of the loading indicators.
+ */
 TextEffectID ShowFillingPercent(int x, int y, int z, uint8 percent, StringID string)
 {
 	Point pt = RemapCoords(x, y, z);
@@ -779,6 +812,11 @@ TextEffectID ShowFillingPercent(int x, int y, int z, uint8 percent, StringID str
 	return AddTextEffect(string, pt.x, pt.y, 0, TE_STATIC);
 }
 
+/**
+ * Update vehicle loading indicators.
+ * @param te_id   TextEffectID to be updated.
+ * @param string  String wich is printed.
+ */
 void UpdateFillingPercent(TextEffectID te_id, uint8 percent, StringID string)
 {
 	assert(string != STR_NULL);
@@ -787,6 +825,10 @@ void UpdateFillingPercent(TextEffectID te_id, uint8 percent, StringID string)
 	UpdateTextEffect(te_id, string);
 }
 
+/**
+ * Hide vehicle loading indicators.
+ * @param *te_id TextEffectID which is supposed to be hidden.
+ */
 void HideFillingPercent(TextEffectID *te_id)
 {
 	if (*te_id == INVALID_TE_ID) return;
diff --git a/src/openttd.h b/src/openttd.h
index cd1f1c341..5b48a4f60 100644
--- a/src/openttd.h
+++ b/src/openttd.h
@@ -14,12 +14,14 @@
 
 #include "core/enum_type.hpp"
 
+/** Mode which defines the state of the game. */
 enum GameMode {
 	GM_MENU,
 	GM_NORMAL,
 	GM_EDITOR,
 };
 
+/** Mode which defines what mode we're switching to. */
 enum SwitchMode {
 	SM_NONE,
 	SM_NEWGAME,
diff --git a/src/road_cmd.cpp b/src/road_cmd.cpp
index 0c2dae288..425d95c2e 100644
--- a/src/road_cmd.cpp
+++ b/src/road_cmd.cpp
@@ -50,7 +50,7 @@ bool RoadVehiclesAreBuilt()
 	return false;
 }
 
-/* Invalid RoadBits on slopes  */
+/** Invalid RoadBits on slopes.  */
 static const RoadBits _invalid_tileh_slopes_road[2][15] = {
 	/* The inverse of the mixable RoadBits on a leveled slope */
 	{