summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorplanetmaker <planetmaker@openttd.org>2011-02-14 19:52:26 +0000
committerplanetmaker <planetmaker@openttd.org>2011-02-14 19:52:26 +0000
commit914f8e9f1d22e1195b06d8d4723a310ea9413b16 (patch)
tree643e9f7fe75e5684851e4787b1699869cd14aede
parent8e4b2c951d92e525873c224de93d8c2cd50f8a6b (diff)
downloadopenttd-914f8e9f1d22e1195b06d8d4723a310ea9413b16.tar.xz
(svn r22080) -Doc: Add doxygen comments to a few functions and improve a few existing comments
-rw-r--r--readme.txt6
-rw-r--r--src/company_base.h2
-rw-r--r--src/console_cmds.cpp64
-rw-r--r--src/economy.cpp1
-rw-r--r--src/misc_gui.cpp44
-rw-r--r--src/openttd.h2
-rw-r--r--src/road_cmd.cpp2
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 */
{