From 914f8e9f1d22e1195b06d8d4723a310ea9413b16 Mon Sep 17 00:00:00 2001 From: planetmaker Date: Mon, 14 Feb 2011 19:52:26 +0000 Subject: [PATCH] (svn r22080) -Doc: Add doxygen comments to a few functions and improve a few existing comments --- readme.txt | 6 ++--- src/company_base.h | 2 +- src/console_cmds.cpp | 64 ++++++++++++++++++++++++++++++++++++++++++-- src/economy.cpp | 1 + src/misc_gui.cpp | 44 +++++++++++++++++++++++++++++- src/openttd.h | 2 ++ src/road_cmd.cpp | 2 +- 7 files changed, 113 insertions(+), 8 deletions(-) diff --git a/readme.txt b/readme.txt index 0ad799c4d2..9c31e6003c 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 6078c8b53c..de1bbeb1bd 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 7cd18bd6e0..539a586637 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 3d2a419ee2..584eea7c7f 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 e30d9c2e85..33c22ed7a2 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 cd1f1c3412..5b48a4f60c 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 0c2dae2886..425d95c2e5 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 */ {