summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2012-01-01 17:22:32 +0000
committeralberth <alberth@openttd.org>2012-01-01 17:22:32 +0000
commit4af8c2d5e17fe04d0e352977993fced13e08b787 (patch)
treeaf38f024a38bf020a217ee4849f72877541399c7 /src
parentda460f6928851dee007fab7637c75a242398370c (diff)
downloadopenttd-4af8c2d5e17fe04d0e352977993fced13e08b787.tar.xz
(svn r23704) -Doc: Doxygen comment fixes and additions.
Diffstat (limited to 'src')
-rw-r--r--src/ai/ai_gui.cpp2
-rw-r--r--src/ai/ai_gui.hpp2
-rw-r--r--src/airport.cpp2
-rw-r--r--src/airport.h4
-rw-r--r--src/animated_tile_func.h2
-rw-r--r--src/company_gui.cpp2
-rw-r--r--src/core/smallmap_type.hpp10
-rw-r--r--src/currency.h15
-rw-r--r--src/depend/depend.cpp14
-rw-r--r--src/depot_cmd.cpp2
-rw-r--r--src/engine_gui.h8
-rw-r--r--src/fileio_type.h4
-rw-r--r--src/goal_base.h2
-rw-r--r--src/heightmap.cpp2
-rw-r--r--src/hotkeys.h2
-rw-r--r--src/industry_cmd.cpp6
-rw-r--r--src/industrytype.h2
-rw-r--r--src/newgrf_airport.h4
-rw-r--r--src/newgrf_commons.cpp4
-rw-r--r--src/newgrf_storage.cpp6
-rw-r--r--src/newgrf_storage.h21
-rw-r--r--src/roadstop_base.h6
-rw-r--r--src/smallmap_gui.cpp2
-rw-r--r--src/strings.cpp18
-rw-r--r--src/subsidy.cpp42
-rw-r--r--src/subsidy_base.h2
-rw-r--r--src/tilematrix_type.hpp2
-rw-r--r--src/townname.cpp2
-rw-r--r--src/townname_func.h2
-rw-r--r--src/train_cmd.cpp144
-rw-r--r--src/vehicle_base.h2
-rw-r--r--src/waypoint_cmd.cpp2
-rw-r--r--src/widgets/dropdown.cpp6
-rw-r--r--src/window.cpp10
-rw-r--r--src/window_func.h2
-rw-r--r--src/window_type.h206
36 files changed, 343 insertions, 221 deletions
diff --git a/src/ai/ai_gui.cpp b/src/ai/ai_gui.cpp
index 7726417b4..1843906b6 100644
--- a/src/ai/ai_gui.cpp
+++ b/src/ai/ai_gui.cpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file ai_gui.cpp Window for configuring the AIs */
+/** @file ai_gui.cpp %Window for configuring the AIs */
#include "../stdafx.h"
#include "../table/sprites.h"
diff --git a/src/ai/ai_gui.hpp b/src/ai/ai_gui.hpp
index ac8cb4a01..9ed647f7e 100644
--- a/src/ai/ai_gui.hpp
+++ b/src/ai/ai_gui.hpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file ai_gui.hpp Window for configuring the AIs */
+/** @file ai_gui.hpp %Window for configuring the AIs */
#ifndef AI_GUI_HPP
#define AI_GUI_HPP
diff --git a/src/airport.cpp b/src/airport.cpp
index 389cbe2b8..1a58be465 100644
--- a/src/airport.cpp
+++ b/src/airport.cpp
@@ -201,7 +201,7 @@ static AirportFTA *AirportBuildAutomata(uint nofelements, const AirportFTAbuildu
/**
* Get the finite state machine of an airport type.
- * @param airport_type Airport type to query FTA from. @see AirportTypes
+ * @param airport_type %Airport type to query FTA from. @see AirportTypes
* @return Finite state machine of the airport.
*/
const AirportFTAClass *GetAirport(const byte airport_type)
diff --git a/src/airport.h b/src/airport.h
index a1acc35ba..7f1183840 100644
--- a/src/airport.h
+++ b/src/airport.h
@@ -71,7 +71,7 @@ enum AirportMovementStates {
STARTTAKEOFF = 11, ///< Airplane has arrived at a runway for take-off.
ENDTAKEOFF = 12, ///< Airplane has reached end-point of the take-off runway.
HELITAKEOFF = 13, ///< Helicopter wants to leave the airport.
- FLYING = 14, ///< Vehicle is flying in the air.
+ FLYING = 14, ///< %Vehicle is flying in the air.
LANDING = 15, ///< Airplane wants to land.
ENDLANDING = 16, ///< Airplane wants to finish landing.
HELILANDING = 17, ///< Helicopter wants to land.
@@ -172,7 +172,7 @@ public:
const AirportMovingData *moving_data; ///< Movement data.
struct AirportFTA *layout; ///< state machine for airport
- const byte *terminals; ///< Array with the number of terminal groups, followed by the number of terminals in each group.
+ const byte *terminals; ///< %Array with the number of terminal groups, followed by the number of terminals in each group.
const byte num_helipads; ///< Number of helipads on this airport. When 0 helicopters will go to normal terminals.
Flags flags; ///< Flags for this airport type.
byte nofelements; ///< number of positions the airport consists of
diff --git a/src/animated_tile_func.h b/src/animated_tile_func.h
index 2e7c0fb69..9634ecdee 100644
--- a/src/animated_tile_func.h
+++ b/src/animated_tile_func.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file animated_tile_func.h Tile animation! */
+/** @file animated_tile_func.h %Tile animation! */
#ifndef ANIMATED_TILE_FUNC_H
#define ANIMATED_TILE_FUNC_H
diff --git a/src/company_gui.cpp b/src/company_gui.cpp
index ff6fce62d..3337a434a 100644
--- a/src/company_gui.cpp
+++ b/src/company_gui.cpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file company_gui.cpp Company related GUIs. */
+/** @file company_gui.cpp %Company related GUIs. */
#include "stdafx.h"
#include "error.h"
diff --git a/src/core/smallmap_type.hpp b/src/core/smallmap_type.hpp
index 57373c442..060a36d27 100644
--- a/src/core/smallmap_type.hpp
+++ b/src/core/smallmap_type.hpp
@@ -17,8 +17,8 @@
/**
* Simple pair of data. Both types have to be POD ("Plain Old Data")!
- * @tvar T Key type.
- * @tvar U Value type.
+ * @tparam T Key type.
+ * @tparam U Value type.
*/
template <typename T, typename U>
struct SmallPair {
@@ -32,9 +32,9 @@ struct SmallPair {
/**
* Implementation of simple mapping class. Both types have to be POD ("Plain Old Data")!
* It has inherited accessors from SmallVector().
- * @tvar T Key type.
- * @tvar U Value type.
- * @tvar S Unit of allocation.
+ * @tparam T Key type.
+ * @tparam U Value type.
+ * @tparam S Unit of allocation.
*
* @see SmallVector
*/
diff --git a/src/currency.h b/src/currency.h
index 60ee5b786..958ad5dee 100644
--- a/src/currency.h
+++ b/src/currency.h
@@ -15,25 +15,26 @@
#include "date_type.h"
#include "strings_type.h"
-static const int CF_NOEURO = 0;
-static const int CF_ISEURO = 1;
-static const uint NUM_CURRENCY = 29;
-static const int CUSTOM_CURRENCY_ID = NUM_CURRENCY - 1;
+static const int CF_NOEURO = 0; ///< Currency never switches to the Euro (as far as known).
+static const int CF_ISEURO = 1; ///< Currency _is_ the Euro.
+static const uint NUM_CURRENCY = 29; ///< Number of currencies.
+static const int CUSTOM_CURRENCY_ID = NUM_CURRENCY - 1; ///< Index of the custom currency.
+/** Specification of a currency. */
struct CurrencySpec {
uint16 rate;
char separator[8];
- Year to_euro;
+ Year to_euro; ///< %Year of switching to the Euro. May also be #CF_NOEURO or #CF_ISEURO.
char prefix[16];
char suffix[16];
/**
* The currency symbol is represented by two possible values, prefix and suffix
- * Usage of one or the other is determined by symbol_pos.
+ * Usage of one or the other is determined by #symbol_pos.
* 0 = prefix
* 1 = suffix
* 2 = both : Special case only for custom currency.
* It is not a spec from Newgrf,
- * rather a way to let users do what they want with custom curency
+ * rather a way to let users do what they want with custom currency
*/
byte symbol_pos;
StringID name;
diff --git a/src/depend/depend.cpp b/src/depend/depend.cpp
index b9c8f7a23..67ceec25f 100644
--- a/src/depend/depend.cpp
+++ b/src/depend/depend.cpp
@@ -149,13 +149,13 @@ enum Token {
TOKEN_ELSE, ///< (#)else in code
TOKEN_ENDIF, ///< (#)endif in code
TOKEN_UNDEF, ///< (#)undef in code
- TOKEN_OR, ///< '||' within #if expression
- TOKEN_AND, ///< '&&' within #if expression
- TOKEN_DEFINED, ///< 'defined' within #if expression
- TOKEN_OPEN, ///< '(' within #if expression
- TOKEN_CLOSE, ///< ')' within #if expression
- TOKEN_NOT, ///< '!' within #if expression
- TOKEN_ZERO, ///< '0' within #if expression
+ TOKEN_OR, ///< '||' within <tt>#if</tt> expression
+ TOKEN_AND, ///< '&&' within <tt>#if</tt> expression
+ TOKEN_DEFINED, ///< 'defined' within <tt>#if</tt> expression
+ TOKEN_OPEN, ///< '(' within <tt>#if</tt> expression
+ TOKEN_CLOSE, ///< ')' within <tt>#if</tt> expression
+ TOKEN_NOT, ///< '!' within <tt>#if</tt> expression
+ TOKEN_ZERO, ///< '0' within <tt>#if</tt> expression
TOKEN_INCLUDE, ///< (#)include in code
};
diff --git a/src/depot_cmd.cpp b/src/depot_cmd.cpp
index da4b0bfb1..7027554bd 100644
--- a/src/depot_cmd.cpp
+++ b/src/depot_cmd.cpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file depot_cmd.cpp Command Handling for depots. */
+/** @file depot_cmd.cpp %Command Handling for depots. */
#include "stdafx.h"
#include "command_func.h"
diff --git a/src/engine_gui.h b/src/engine_gui.h
index 4f6ec656c..14fe0f9d7 100644
--- a/src/engine_gui.h
+++ b/src/engine_gui.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file engine_gui.h Engine GUI functions, used by build_vehicle_gui and autoreplace_gui */
+/** @file engine_gui.h %Engine GUI functions, used by build_vehicle_gui and autoreplace_gui */
#ifndef ENGINE_GUI_H
#define ENGINE_GUI_H
@@ -18,9 +18,9 @@
typedef GUIList<EngineID, CargoID> GUIEngineList;
-typedef int CDECL EngList_SortTypeFunction(const EngineID*, const EngineID*); ///< argument type for EngList_Sort()
-void EngList_Sort(GUIEngineList *el, EngList_SortTypeFunction compare); ///< sort of the engine list
-void EngList_SortPartial(GUIEngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items); ///< sort of specified portion of the engine list
+typedef int CDECL EngList_SortTypeFunction(const EngineID*, const EngineID*); ///< argument type for #EngList_Sort.
+void EngList_Sort(GUIEngineList *el, EngList_SortTypeFunction compare);
+void EngList_SortPartial(GUIEngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items);
StringID GetEngineCategoryName(EngineID engine);
StringID GetEngineInfoString(EngineID engine);
diff --git a/src/fileio_type.h b/src/fileio_type.h
index 98180fe66..516bf0e35 100644
--- a/src/fileio_type.h
+++ b/src/fileio_type.h
@@ -28,8 +28,8 @@ enum Subdirectory {
BASESET_DIR, ///< Subdirectory for all base data (base sets, intro game)
NEWGRF_DIR, ///< Subdirectory for all NewGRFs
LANG_DIR, ///< Subdirectory for all translation files
- AI_DIR, ///< Subdirectory for all AI files
- AI_LIBRARY_DIR,///< Subdirectory for all AI libraries
+ AI_DIR, ///< Subdirectory for all %AI files
+ AI_LIBRARY_DIR,///< Subdirectory for all %AI libraries
GAME_DIR, ///< Subdirectory for all game scripts
GAME_LIBRARY_DIR, ///< Subdirectory for all GS libraries
NUM_SUBDIRS, ///< Number of subdirectories
diff --git a/src/goal_base.h b/src/goal_base.h
index 2d97782ed..7cdd0aab2 100644
--- a/src/goal_base.h
+++ b/src/goal_base.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file goal_base.h Goal base class. */
+/** @file goal_base.h %Goal base class. */
#ifndef GOAL_BASE_H
#define GOAL_BASE_H
diff --git a/src/heightmap.cpp b/src/heightmap.cpp
index 1e6531fb0..be51dc004 100644
--- a/src/heightmap.cpp
+++ b/src/heightmap.cpp
@@ -28,7 +28,7 @@
*/
static inline byte RGBToGrayscale(byte red, byte green, byte blue)
{
- /* To avoid doubles and stuff, multiple it with a total of 65536 (16bits), then
+ /* To avoid doubles and stuff, multiply it with a total of 65536 (16bits), then
* divide by it to normalize the value to a byte again. */
return ((red * 19595) + (green * 38470) + (blue * 7471)) / 65536;
}
diff --git a/src/hotkeys.h b/src/hotkeys.h
index 79740f3d4..b87787e1b 100644
--- a/src/hotkeys.h
+++ b/src/hotkeys.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file hotkeys.h Hotkey related functions. */
+/** @file hotkeys.h %Hotkey related functions. */
#ifndef HOTKEYS_H
#define HOTKEYS_H
diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp
index 2126a6cac..349e9f381 100644
--- a/src/industry_cmd.cpp
+++ b/src/industry_cmd.cpp
@@ -1321,8 +1321,8 @@ static CheckNewIndustryProc * const _check_new_industry_procs[CHECK_END] = {
* @param [out] town Pointer to return town for the new industry, \c NULL is written if no good town can be found.
* @return Succeeded or failed command.
*
- * @precond \c *t != NULL
- * @postcon \c *t points to a town on success, and \c NULL on failure.
+ * @pre \c *t != NULL
+ * @post \c *t points to a town on success, and \c NULL on failure.
*/
static CommandCost FindTownForIndustry(TileIndex tile, int type, Town **t)
{
@@ -2064,7 +2064,7 @@ void IndustryBuildData::Reset()
void IndustryBuildData::MonthlyLoop()
{
static const int NEWINDS_PER_MONTH = 0x38000 / (10 * 12); // lower 16 bits is a float fraction, 3.5 industries per decade, divided by 10 * 12 months.
- if (_settings_game.difficulty.industry_density == ID_FUND_ONLY) return; // 'no industries' setting,
+ if (_settings_game.difficulty.industry_density == ID_FUND_ONLY) return; // 'no industries' setting.
/* To prevent running out of unused industries for the player to connect,
* add a fraction of new industries each month, but only if the manager can keep up. */
diff --git a/src/industrytype.h b/src/industrytype.h
index fa7534ad9..b56534304 100644
--- a/src/industrytype.h
+++ b/src/industrytype.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file industrytype.h Industry type specs. */
+/** @file industrytype.h %Industry type specs. */
#ifndef INDUSTRYTYPE_H
#define INDUSTRYTYPE_H
diff --git a/src/newgrf_airport.h b/src/newgrf_airport.h
index 3b5d0004a..87f921105 100644
--- a/src/newgrf_airport.h
+++ b/src/newgrf_airport.h
@@ -118,8 +118,8 @@ struct AirportSpec {
SpriteID preview_sprite; ///< preview sprite for this airport
uint16 maintenance_cost; ///< maintenance cost mulltiplier
/* Newgrf data */
- bool enabled; ///< entity still avaible (by default true).newgrf can disable it, though
- struct GRFFileProps grf_prop; ///< properties related the the grf file
+ bool enabled; ///< Entity still available (by default true). Newgrf can disable it, though.
+ struct GRFFileProps grf_prop; ///< Properties related to the grf file.
static const AirportSpec *Get(byte type);
static AirportSpec *GetWithoutOverride(byte type);
diff --git a/src/newgrf_commons.cpp b/src/newgrf_commons.cpp
index d25e3245e..cdfe9e7a0 100644
--- a/src/newgrf_commons.cpp
+++ b/src/newgrf_commons.cpp
@@ -8,8 +8,8 @@
*/
/**
- * @file newgrf_commons.cpp Implementation of the class OverrideManagerBase
- * and its descendance, present and futur
+ * @file newgrf_commons.cpp Implementation of the class %OverrideManagerBase
+ * and its descendance, present and future.
*/
#include "stdafx.h"
diff --git a/src/newgrf_storage.cpp b/src/newgrf_storage.cpp
index 535a9f8fb..ac91a122f 100644
--- a/src/newgrf_storage.cpp
+++ b/src/newgrf_storage.cpp
@@ -40,14 +40,14 @@ void AddChangedStorage(BaseStorageArray *storage)
}
/**
- * Clear the changes made since the last ClearStorageChanges.
+ * Clear the changes made since the last #ClearStorageChanges.
* This is done for *all* storages that have been registered to with
- * AddChangedStorage since the previous ClearStorageChanges.
+ * #AddChangedStorage since the previous #ClearStorageChanges.
*
* This can be done in two ways:
* - saving the changes permanently
* - reverting to the previous version
- * @param keep_changes do we save or revert the changes since the last ClearChanges?
+ * @param keep_changes do we save or revert the changes since the last #ClearChanges?
*/
void ClearStorageChanges(bool keep_changes)
{
diff --git a/src/newgrf_storage.h b/src/newgrf_storage.h
index 2ea3e3d8e..fda3b3b1a 100644
--- a/src/newgrf_storage.h
+++ b/src/newgrf_storage.h
@@ -19,16 +19,15 @@
* Base class for all NewGRF storage arrays. Nothing fancy, only here
* so we have a generalised class to use.
*/
-struct BaseStorageArray
-{
+struct BaseStorageArray {
virtual ~BaseStorageArray();
/**
- * Clear the changes made since the last ClearChanges.
+ * Clear the changes made since the last #ClearChanges.
* This can be done in two ways:
* - saving the changes permanently
* - reverting to the previous version
- * @param keep_changes do we save or revert the changes since the last ClearChanges?
+ * @param keep_changes do we save or revert the changes since the last #ClearChanges?
*/
virtual void ClearChanges(bool keep_changes) = 0;
@@ -42,9 +41,9 @@ struct BaseStorageArray
/**
* Class for persistent storage of data.
- * On ClearChanges that data is either reverted or saved.
- * @param TYPE the type of variable to store.
- * @param SIZE the size of the array.
+ * On #ClearChanges that data is either reverted or saved.
+ * @tparam TYPE the type of variable to store.
+ * @tparam SIZE the size of the array.
*/
template <typename TYPE, uint SIZE>
struct PersistentStorageArray : BaseStorageArray {
@@ -129,9 +128,9 @@ struct PersistentStorageArray : BaseStorageArray {
/**
* Class for temporary storage of data.
- * On ClearChanges that data is always zero-ed.
- * @param TYPE the type of variable to store.
- * @param SIZE the size of the array.
+ * On #ClearChanges that data is always zero-ed.
+ * @tparam TYPE the type of variable to store.
+ * @tparam SIZE the size of the array.
*/
template <typename TYPE, uint SIZE>
struct TemporaryStorageArray : BaseStorageArray {
@@ -191,7 +190,7 @@ extern PersistentStoragePool _persistent_storage_pool;
/**
* Class for pooled persistent storage of data.
- * On ClearChanges that data is always zero-ed.
+ * On #ClearChanges that data is always zero-ed.
*/
struct PersistentStorage : PersistentStorageArray<int32, 16>, PersistentStoragePool::PoolItem<&_persistent_storage_pool> {
uint32 grfid; ///< GRFID associated to this persistent storage. A value of zero means "default".
diff --git a/src/roadstop_base.h b/src/roadstop_base.h
index 1273bbe66..ee470db8d 100644
--- a/src/roadstop_base.h
+++ b/src/roadstop_base.h
@@ -109,7 +109,7 @@ struct RoadStop : RoadStopPool::PoolItem<&_roadstop_pool> {
/**
* Makes an entrance occupied or free
- * @param busy if true, marks busy; free otherwise
+ * @param busy If true, marks busy; free otherwise.
*/
inline void SetEntranceBusy(bool busy)
{
@@ -118,7 +118,7 @@ struct RoadStop : RoadStopPool::PoolItem<&_roadstop_pool> {
/**
* Get the drive through road stop entry struct for the given direction.
- * @param direction the direciton to get the entry for
+ * @param dir The direction to get the entry for.
* @return the entry
*/
inline const Entry *GetEntry(DiagDirection dir) const
@@ -128,7 +128,7 @@ struct RoadStop : RoadStopPool::PoolItem<&_roadstop_pool> {
/**
* Get the drive through road stop entry struct for the given direction.
- * @param direction the direciton to get the entry for
+ * @param dir The direction to get the entry for.
* @return the entry
*/
inline Entry *GetEntry(DiagDirection dir)
diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp
index a04693f1a..b3786310d 100644
--- a/src/smallmap_gui.cpp
+++ b/src/smallmap_gui.cpp
@@ -1087,7 +1087,7 @@ public:
/**
* Compute height given a number of columns.
- * @param Number of columns.
+ * @param num_columns Number of columns.
* @return Needed height for displaying the smallmap legends in pixels.
*/
uint GetLegendHeight(uint num_columns) const
diff --git a/src/strings.cpp b/src/strings.cpp
index 65fdec77e..a4be25b59 100644
--- a/src/strings.cpp
+++ b/src/strings.cpp
@@ -419,8 +419,8 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, Money n
number = -number;
}
- /* Add prefix part, folowing symbol_pos specification.
- * Here, it can can be either 0 (prefix) or 2 (both prefix anf suffix).
+ /* Add prefix part, following symbol_pos specification.
+ * Here, it can can be either 0 (prefix) or 2 (both prefix and suffix).
* The only remaining value is 1 (suffix), so everything that is not 1 */
if (spec->symbol_pos != 1) buff = strecpy(buff, spec->prefix, last);
@@ -443,8 +443,8 @@ static char *FormatGenericCurrency(char *buff, const CurrencySpec *spec, Money n
buff = FormatNumber(buff, number, last, separator);
buff = strecpy(buff, multiplier, last);
- /* Add suffix part, folowing symbol_pos specification.
- * Here, it can can be either 1 (suffix) or 2 (both prefix anf suffix).
+ /* Add suffix part, following symbol_pos specification.
+ * Here, it can can be either 1 (suffix) or 2 (both prefix and suffix).
* The only remaining value is 1 (prefix), so everything that is not 0 */
if (spec->symbol_pos != 0) buff = strecpy(buff, spec->suffix, last);
@@ -1818,7 +1818,7 @@ const LanguageMetadata *GetLanguage(byte newgrflangid)
}
/**
- * Reads the language file header and checks compatability.
+ * Reads the language file header and checks compatibility.
* @param file the file to read
* @param hdr the place to write the header information to
* @return true if and only if the language file is of a compatible version
@@ -1874,8 +1874,8 @@ static void GetLanguageList(const char *path)
}
/**
- * Make a list of the available language packs. put the data in
- * _dynlang struct.
+ * Make a list of the available language packs. Put the data in
+ * #_languages list.
*/
void InitializeLanguagePacks()
{
@@ -1892,7 +1892,7 @@ void InitializeLanguagePacks()
const char *lang = GetCurrentLocale("LC_MESSAGES");
if (lang == NULL) lang = "en_GB";
- const LanguageMetadata *chosen_language = NULL; ///< Matching the language in the configuartion file or the current locale
+ const LanguageMetadata *chosen_language = NULL; ///< Matching the language in the configuration file or the current locale
const LanguageMetadata *language_fallback = NULL; ///< Using pt_PT for pt_BR locale when pt_BR is not available
const LanguageMetadata *en_GB_fallback = _languages.Begin(); ///< Fallback when no locale-matching language has been found
@@ -1900,7 +1900,7 @@ void InitializeLanguagePacks()
for (const LanguageMetadata *lng = _languages.Begin(); lng != _languages.End(); lng++) {
/* We are trying to find a default language. The priority is by
* configuration file, local environment and last, if nothing found,
- * english. */
+ * English. */
const char *lang_file = strrchr(lng->file, PATHSEPCHAR) + 1;
if (strcmp(lang_file, _config_language_file) == 0) {
chosen_language = lng;
diff --git a/src/subsidy.cpp b/src/subsidy.cpp
index 5183b1d2e..1b7362c0a 100644
--- a/src/subsidy.cpp
+++ b/src/subsidy.cpp
@@ -28,7 +28,7 @@
#include "table/strings.h"
-SubsidyPool _subsidy_pool("Subsidy");
+SubsidyPool _subsidy_pool("Subsidy"); ///< Pool for the subsidies.
INSTANTIATE_POOL_METHODS(Subsidy)
/**
@@ -65,6 +65,12 @@ void Subsidy::AwardTo(CompanyID company)
InvalidateWindowData(WC_SUBSIDIES_LIST, 0);
}
+/**
+ * Setup the string parameters for printing the subsidy at the screen, and compute the news reference for the subsidy.
+ * @param s %Subsidy being printed.
+ * @param mode Unit of cargo used, \c true means general name, \c false means singular form.
+ * @return Reference of the subsidy in the news system.
+ */
Pair SetupSubsidyDecodeParam(const Subsidy *s, bool mode)
{
NewsReferenceType reftype1 = NR_NONE;
@@ -121,6 +127,7 @@ static inline void SetPartOfSubsidyFlag(SourceType type, SourceID index, PartOfS
}
}
+/** Perform a full rebuild of the subsidies cache. */
void RebuildSubsidisedSourceAndDestinationCache()
{
Town *t;
@@ -136,6 +143,11 @@ void RebuildSubsidisedSourceAndDestinationCache()
}
}
+/**
+ * Delete the subsidies associated with a given cargo source type and id.
+ * @param type Cargo source type of the id.
+ * @param index Id to remove.
+ */
void DeleteSubsidyWith(SourceType type, SourceID index)
{
bool dirty = false;
@@ -154,6 +166,15 @@ void DeleteSubsidyWith(SourceType type, SourceID index)
}
}
+/**
+ * Check whether a specific subsidy already exists.
+ * @param cargo Cargo type.
+ * @param src_type Type of source of the cargo, affects interpretation of \a src.
+ * @param src Id of the source.
+ * @param dst_type Type of the destination of the cargo, affects interpretation of \a dst.
+ * @param dst Id of the destination.
+ * @return \c true if the subsidy already exists, \c false if not.
+ */
static bool CheckSubsidyDuplicate(CargoID cargo, SourceType src_type, SourceID src, SourceType dst_type, SourceID dst)
{
const Subsidy *s;
@@ -167,7 +188,8 @@ static bool CheckSubsidyDuplicate(CargoID cargo, SourceType src_type, SourceID s
return false;
}
-/** Checks if the source and destination of a subsidy are inside the distance limit.
+/**
+ * Checks if the source and destination of a subsidy are inside the distance limit.
* @param src_type Type of #src.
* @param src Index of source.
* @param dst_type Type of #dst.
@@ -182,7 +204,8 @@ static bool CheckSubsidyDistance(SourceType src_type, SourceID src, SourceType d
return (DistanceManhattan(tile_src, tile_dst) <= SUBSIDY_MAX_DISTANCE);
}
-/** Creates a subsidy with the given parameters.
+/**
+ * Creates a subsidy with the given parameters.
* @param cid Subsidised cargo.
* @param src_type Type of #src.
* @param src Index of source.
@@ -266,7 +289,8 @@ CommandCost CmdCreateSubsidy(TileIndex tile, DoCommandFlag flags, uint32 p1, uin
return CommandCost();
}
-/** Tries to create a passenger subsidy between two towns.
+/**
+ * Tries to create a passenger subsidy between two towns.
* @return True iff the subsidy was created.
*/
bool FindSubsidyPassengerRoute()
@@ -295,7 +319,8 @@ bool FindSubsidyPassengerRoute()
bool FindSubsidyCargoDestination(CargoID cid, SourceType src_type, SourceID src);
-/** Tries to create a cargo subsidy with a town as source.
+/**
+ * Tries to create a cargo subsidy with a town as source.
* @return True iff the subsidy was created.
*/
bool FindSubsidyTownCargoRoute()
@@ -331,7 +356,8 @@ bool FindSubsidyTownCargoRoute()
return FindSubsidyCargoDestination(cid, src_type, src);
}
-/** Tries to create a cargo subsidy with an industry as source.
+/**
+ * Tries to create a cargo subsidy with an industry as source.
* @return True iff the subsidy was created.
*/
bool FindSubsidyIndustryCargoRoute()
@@ -368,7 +394,8 @@ bool FindSubsidyIndustryCargoRoute()
return FindSubsidyCargoDestination(cid, src_type, src);
}
-/** Tries to find a suitable destination for the given source and cargo.
+/**
+ * Tries to find a suitable destination for the given source and cargo.
* @param cid Subsidized cargo.
* @param src_type Type of #src.
* @param src Index of source.
@@ -425,6 +452,7 @@ bool FindSubsidyCargoDestination(CargoID cid, SourceType src_type, SourceID src)
return true;
}
+/** Perform the monthly update of open subsidies, and try to create a new one. */
void SubsidyMonthlyLoop()
{
bool modified = false;
diff --git a/src/subsidy_base.h b/src/subsidy_base.h
index eec035b14..f12fbc4b9 100644
--- a/src/subsidy_base.h
+++ b/src/subsidy_base.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file subsidy_base.h Subsidy base class. */
+/** @file subsidy_base.h %Subsidy base class. */
#ifndef SUBSIDY_BASE_H
#define SUBSIDY_BASE_H
diff --git a/src/tilematrix_type.hpp b/src/tilematrix_type.hpp
index fd5a94abc..79f24aa7e 100644
--- a/src/tilematrix_type.hpp
+++ b/src/tilematrix_type.hpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file tilematrix_type.hpp */
+/** @file tilematrix_type.hpp Template for storing a value per area of the map. */
#ifndef TILEMATRIX_TYPE_HPP
#define TILEMATRIX_TYPE_HPP
diff --git a/src/townname.cpp b/src/townname.cpp
index ef6cd2603..1e0b43d8a 100644
--- a/src/townname.cpp
+++ b/src/townname.cpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file townname.cpp Town name generators. */
+/** @file townname.cpp %Town name generators. */
#include "stdafx.h"
#include "string_func.h"
diff --git a/src/townname_func.h b/src/townname_func.h
index 0d65fc16b..092556978 100644
--- a/src/townname_func.h
+++ b/src/townname_func.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file townname_func.h Town name generator stuff. */
+/** @file townname_func.h %Town name generator stuff. */
#ifndef TOWNNAME_FUNC_H
#define TOWNNAME_FUNC_H
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
index 1015d8dd3..cfce4b819 100644
--- a/src/train_cmd.cpp
+++ b/src/train_cmd.cpp
@@ -425,6 +425,7 @@ int Train::GetCurrentMaxSpeed() const
return min(max_speed, this->gcache.cached_max_track_speed);
}
+/** Update acceleration of the train from the cached power and weight. */
void Train::UpdateAcceleration()
{
assert(this->IsFrontEngine());
@@ -463,6 +464,12 @@ static SpriteID GetDefaultTrainSprite(uint8 spritenum, Direction direction)
return ((direction + _engine_sprite_add[spritenum]) & _engine_sprite_and[spritenum]) + _engine_sprite_base[spritenum];
}
+/**
+ * Get the sprite to display the train.
+ * @param direction Direction of view/travel.
+ * @param image_type Visualisation context.
+ * @return Sprite to display.
+ */
SpriteID Train::GetImage(Direction direction, EngineImageType image_type) const
{
uint8 spritenum = this->spritenum;
@@ -740,7 +747,10 @@ CommandCost CmdBuildRailVehicle(TileIndex tile, DoCommandFlag flags, const Engin
return CommandCost();
}
-
+/**
+ * Is the whole consist the in a depot?
+ * @return \c true iff all vehicles of the train are in a depot.
+ */
bool Train::IsInDepot() const
{
/* Is the front engine stationary in the depot? */
@@ -754,6 +764,10 @@ bool Train::IsInDepot() const
return true;
}
+/**
+ * Is the train stopped in a depot?
+ * @return True if the train is stopped in a depot, else false.
+ */
bool Train::IsStoppedInDepot() const
{
/* Are we stopped? Of course wagons don't really care... */
@@ -1452,7 +1466,10 @@ void Train::UpdateDeltaXY(Direction direction)
}
}
-/** Mark a train as stuck and stop it if it isn't stopped right now. */
+/**
+ * Mark a train as stuck and stop it if it isn't stopped right now.
+ * @param v %Train to mark as being stuck.
+ */
static void MarkTrainAsStuck(Train *v)
{
if (!HasBit(v->flags, VRF_TRAIN_STUCK)) {
@@ -1470,6 +1487,13 @@ static void MarkTrainAsStuck(Train *v)
}
}
+/**
+ * Swap the two up/down flags in two ways:
+ * - Swap values of \a swap_flag1 and \a swap_flag2, and
+ * - If going up previously (#GVF_GOINGUP_BIT set), the #GVF_GOINGDOWN_BIT is set, and vice versa.
+ * @param swap_flag1 [inout] First train flag.
+ * @param swap_flag2 [inout] Second train flag.
+ */
static void SwapTrainFlags(uint16 *swap_flag1, uint16 *swap_flag2)
{
uint16 flag1 = *swap_flag1;
@@ -1527,6 +1551,12 @@ static void UpdateStatusAfterSwap(Train *v)
v->UpdateViewport(true, true);
}
+/**
+ * Swap vehicles \a l and \a r in consist \a v, and reverse their direction.
+ * @param v Consist to change.
+ * @param l %Vehicle index in the consist of the first vehicle.
+ * @param r %Vehicle index in the consist of the second vehicle.
+ */
void ReverseTrainSwapVeh(Train *v, int l, int r)
{
Train *a, *b;
@@ -1745,7 +1775,10 @@ static void AdvanceWagonsAfterSwap(Train *v)
}
}
-
+/**
+ * Turn a train around.
+ * @param v %Train to turn around.
+ */
void ReverseTrainDirection(Train *v)
{
if (IsRailDepotTile(v->tile)) {
@@ -1932,8 +1965,11 @@ CommandCost CmdForceTrainProceed(TileIndex tile, DoCommandFlag flags, uint32 p1,
}
/**
- * returns the tile of a depot to goto to. The given vehicle must not be
- * crashed!
+ * Try to find a depot nearby.
+ * @param v %Train that wants a depot.
+ * @param max_distance Maximal search distance.
+ * @return Information where the closest train depot is located.
+ * @pre The given vehicle must not be crashed!
*/
static FindDepotData FindClosestTrainDepot(Train *v, int max_distance)
{
@@ -1952,6 +1988,13 @@ static FindDepotData FindClosestTrainDepot(Train *v, int max_distance)
}
}
+/**
+ * Locate the closest depot for this consist, and return the information to the caller.
+ * @param location [out] If not \c NULL and a depot is found, store its location in the given address.
+ * @param destination [out] If not \c NULL and a depot is found, store its index in the given address.
+ * @param reverse [out] If not \c NULL and a depot is found, store reversal information in the given address.
+ * @return A depot has been found.
+ */
bool Train::FindClosestDepot(TileIndex *location, DestinationID *destination, bool *reverse)
{
FindDepotData tfdd = FindClosestTrainDepot(this, 0);
@@ -1964,6 +2007,7 @@ bool Train::FindClosestDepot(TileIndex *location, DestinationID *destination, bo
return true;
}
+/** Play a sound for a train leaving the station. */
void Train::PlayLeaveStationSound() const
{
static const SoundFx sfx[] = {
@@ -1980,7 +2024,10 @@ void Train::PlayLeaveStationSound() const
SndPlayVehicleFx(sfx[RailVehInfo(engtype)->engclass], this);
}
-/** Check if the train is on the last reserved tile and try to extend the path then. */
+/**
+ * Check if the train is on the last reserved tile and try to extend the path then.
+ * @param v %Train that needs its path extended.
+ */
static void CheckNextTrainTile(Train *v)
{
/* Don't do any look-ahead if path_backoff_interval is 255. */
@@ -2038,6 +2085,11 @@ static void CheckNextTrainTile(Train *v)
}
}
+/**
+ * Will the train stay in the depot the next tick?
+ * @param v %Train to check.
+ * @return True if it stays in the depot, false otherwise.
+ */
static bool CheckTrainStayInDepot(Train *v)
{
/* bail out if not all wagons are in the same depot or not in a depot at all */
@@ -2113,7 +2165,12 @@ static bool CheckTrainStayInDepot(Train *v)
return false;
}
-/** Clear the reservation of a tile that was just left by a wagon on track_dir. */
+/**
+ * Clear the reservation of \a tile that was just left by a wagon on \a track_dir.
+ * @param v %Train owning the reservation.
+ * @param tile Tile with reservation to clear.
+ * @param track_dir Track direction to clear.
+ */
static void ClearPathReservation(const Train *v, TileIndex tile, Trackdir track_dir)
{
DiagDirection dir = TrackdirToExitdir(track_dir);
@@ -2147,7 +2204,12 @@ static void ClearPathReservation(const Train *v, TileIndex tile, Trackdir track_
}
}
-/** Free the reserved path in front of a vehicle. */
+/**
+ * Free the reserved path in front of a vehicle.
+ * @param v %Train owning the reserved path.
+ * @param origin %Tile to start clearing (if #INVALID_TILE, use the current tile of \a v).
+ * @param orig_td Track direction (if #INVALID_TRACKDIR, use the track direction of \a v).
+ */
void FreeTrainTrackReservation(const Train *v, TileIndex origin, Trackdir orig_td)
{
assert(v->IsFrontEngine());
@@ -2335,8 +2397,7 @@ static bool TryReserveSafeTrack(const Train *v, TileIndex tile, Trackdir td, boo
}
/** This class will save the current order of a vehicle and restore it on destruction. */
-class VehicleOrderSaver
-{
+class VehicleOrderSaver {
private:
Train *v;
Order old_order;
@@ -2663,6 +2724,11 @@ static bool CheckReverseTrain(const Train *v)
}
}
+/**
+ * Get the location of the next station to visit.
+ * @param station Next station to visit.
+ * @return Location of the new station.
+ */
TileIndex Train::GetOrderStationLocation(StationID station)
{
if (station == this->last_station_visited) this->last_station_visited = INVALID_STATION;
@@ -2677,6 +2743,7 @@ TileIndex Train::GetOrderStationLocation(StationID station)
return st->xy;
}
+/** Goods at the consist have changed, update the graphics, cargo, and acceleration. */
void Train::MarkDirty()
{
Train *v = this;
@@ -2747,12 +2814,15 @@ static inline bool CheckCompatibleRail(const Train *v, TileIndex tile)
(!v->IsFrontEngine() || HasBit(v->compatible_railtypes, GetRailType(tile)));
}
+/** Data structure for storing engine speed changes of a rail type. */
struct RailtypeSlowdownParams {
- byte small_turn, large_turn;
- byte z_up; // fraction to remove when moving up
- byte z_down; // fraction to remove when moving down
+ byte small_turn; ///< Speed change due to a small turn.
+ byte large_turn; ///< Speed change due to a large turn.
+ byte z_up; ///< Fraction to remove when moving up.
+ byte z_down; ///< Fraction to add when moving down.
};
+/** Speed update fractions for each rail type. */
static const RailtypeSlowdownParams _railtype_slowdown[] = {
/* normal accel */
{256 / 4, 256 / 2, 256 / 4, 2}, ///< normal
@@ -2761,7 +2831,11 @@ static const RailtypeSlowdownParams _railtype_slowdown[] = {
{0, 256 / 2, 256 / 4, 2}, ///< maglev
};
-/** Modify the speed of the vehicle due to a change in altitude */
+/**
+ * Modify the speed of the vehicle due to a change in altitude.
+ * @param v %Train to update.
+ * @param old_z Previous height.
+ */
static inline void AffectSpeedByZChange(Train *v, int old_z)
{
if (old_z == v->z_pos || _settings_game.vehicle.train_acceleration_model != AM_ORIGINAL) return;
@@ -2790,9 +2864,7 @@ static bool TrainMovedChangeSignals(TileIndex tile, DiagDirection dir)
return false;
}
-/**
- * Tries to reserve track under whole train consist
- */
+/** Tries to reserve track under whole train consist. */
void Train::ReserveTrackUnderConsist() const
{
for (const Train *u = this; u != NULL; u = u->Next()) {
@@ -2809,6 +2881,12 @@ void Train::ReserveTrackUnderConsist() const
}
}
+/**
+ * The train vehicle crashed!
+ * Update its status and other parts around it.
+ * @param flooded Crash was caused by flooding.
+ * @return Number of people killed.
+ */
uint Train::Crash(bool flooded)
{
uint pass = 0;
@@ -2866,11 +2944,18 @@ static uint TrainCrashed(Train *v)
return num;
}
+/** Temporary data storage for testing collisions. */
struct TrainCollideChecker {
- Train *v; ///< vehicle we are testing for collision
- uint num; ///< number of victims if train collided
+ Train *v; ///< %Vehicle we are testing for collision.
+ uint num; ///< Total number of victims if train collided.
};
+/**
+ * Collision test function.
+ * @param v %Train vehicle to test collision with.
+ * @param data %Train being examined.
+ * @return \c NULL (always continue search)
+ */
static Vehicle *FindTrainCollideEnum(Vehicle *v, void *data)
{
TrainCollideChecker *tcc = (TrainCollideChecker*)data;
@@ -2916,6 +3001,7 @@ static Vehicle *FindTrainCollideEnum(Vehicle *v, void *data)
* so, destroys this vehicle, and the other vehicle if its subtype has TS_Front.
* Reports the incident in a flashy news item, modifies station ratings and
* plays a sound.
+ * @param v %Train to test.
*/
static bool CheckTrainCollision(Train *v)
{
@@ -3759,8 +3845,10 @@ static bool TrainLocoHandler(Train *v, bool mode)
return true;
}
-
-
+/**
+ * Get running cost for the train consist.
+ * @return Yearly running costs.
+ */
Money Train::GetRunningCost() const
{
Money cost = 0;
@@ -3782,7 +3870,10 @@ Money Train::GetRunningCost() const
return cost;
}
-
+/**
+ * Update train vehicle data for a tick.
+ * @return True if the vehicle still exists, false if it has ceased to exist (front of consists only).
+ */
bool Train::Tick()
{
this->tick_counter++;
@@ -3806,6 +3897,10 @@ bool Train::Tick()
return true;
}
+/**
+ * Check whether a train needs serivce, and if so, find a depot or service it.
+ * @return v %Train to check.
+ */
static void CheckIfTrainNeedsService(Train *v)
{
if (Company::Get(v->owner)->settings.vehicle.servint_trains == 0 || !v->NeedsAutomaticServicing()) return;
@@ -3848,6 +3943,7 @@ static void CheckIfTrainNeedsService(Train *v)
SetWindowWidgetDirty(WC_VEHICLE_VIEW, v->index, WID_VV_START_STOP);
}
+/** Update day counters of the train vehicle. */
void Train::OnNewDay()
{
AgeVehicle(this);
@@ -3882,6 +3978,10 @@ void Train::OnNewDay()
}
}
+/**
+ * Get the tracks of the train vehicle.
+ * @return Current tracks of the vehicle.
+ */
Trackdir Train::GetVehicleTrackdir() const
{
if (this->vehstatus & VS_CRASHED) return INVALID_TRACKDIR;
diff --git a/src/vehicle_base.h b/src/vehicle_base.h
index 16d258832..215340ff0 100644
--- a/src/vehicle_base.h
+++ b/src/vehicle_base.h
@@ -511,7 +511,7 @@ public:
}
/**
- * Get the vehicle at offset #n of this vehicle chain.
+ * Get the vehicle at offset \a n of this vehicle chain.
* @param n Offset from the current vehicle.
* @return The new vehicle or NULL if the offset is out-of-bounds.
*/
diff --git a/src/waypoint_cmd.cpp b/src/waypoint_cmd.cpp
index 3043b3804..74648ae14 100644
--- a/src/waypoint_cmd.cpp
+++ b/src/waypoint_cmd.cpp
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file waypoint_cmd.cpp Command Handling for waypoints. */
+/** @file waypoint_cmd.cpp %Command Handling for waypoints. */
#include "stdafx.h"
diff --git a/src/widgets/dropdown.cpp b/src/widgets/dropdown.cpp
index 9c73d3fb3..6f982b5a0 100644
--- a/src/widgets/dropdown.cpp
+++ b/src/widgets/dropdown.cpp
@@ -422,14 +422,14 @@ void ShowDropDownList(Window *w, DropDownList *list, int selected, int button, u
/**
* Show a dropdown menu window near a widget of the parent window.
- * The result code of the items is their index in the #strings list.
+ * The result code of the items is their index in the \a strings list.
* @param w Parent window that wants the dropdown menu.
* @param strings Menu list, end with #INVALID_STRING_ID
* @param selected Index of initial selected item.
- * @param button Button widget number of the parent window #w that wants the dropdown menu.
+ * @param button Button widget number of the parent window \a w that wants the dropdown menu.
* @param disabled_mask Bitmask for diabled items (items with their bit set are not copied to the dropdown list).
* @param hidden_mask Bitmask for hidden items (items with their bit set are displayed, but not selectable in the dropdown list).
- * @param width Width of the dropdown menu. If \c 0, use the width of parent widget #button.
+ * @param width Width of the dropdown menu. If \c 0, use the width of parent widget \a button.
*/
void ShowDropDownMenu(Window *w, const StringID *strings, int selected, int button, uint32 disabled_mask, uint32 hidden_mask, uint width)
{
diff --git a/src/window.cpp b/src/window.cpp
index 9cb201118..c114467b0 100644
--- a/src/window.cpp
+++ b/src/window.cpp
@@ -730,8 +730,8 @@ void Window::SetShaded(bool make_shaded)
/**
* Find the Window whose parent pointer points to this window
* @param w parent Window to find child of
- * @param wc Window class of the window to remove; WC_INVALID if class does not matter
- * @return a Window pointer that is the child of w, or NULL otherwise
+ * @param wc Window class of the window to remove; #WC_INVALID if class does not matter
+ * @return a Window pointer that is the child of \a w, or \c NULL otherwise
*/
static Window *FindChildWindow(const Window *w, WindowClass wc)
{
@@ -745,7 +745,7 @@ static Window *FindChildWindow(const Window *w, WindowClass wc)
/**
* Delete all children a window might have in a head-recursive manner
- * @param wc Window class of the window to remove; WC_INVALID if class does not matter
+ * @param wc Window class of the window to remove; #WC_INVALID if class does not matter
*/
void Window::DeleteChildWindows(WindowClass wc) const
{
@@ -805,7 +805,7 @@ Window *FindWindowById(WindowClass cls, WindowNumber number)
/**
* Find any window by its class. Useful when searching for a window that uses
- * the window number as a WindowType, like WC_SEND_NETWORK_MSG.
+ * the window number as a #WindowType, like #WC_SEND_NETWORK_MSG.
* @param cls Window class
* @return Pointer to the found window, or \c NULL if not available
*/
@@ -2532,7 +2532,7 @@ static void CheckSoftLimit()
deletable_count++;
}
- /* We've ot reached the soft limit yet */
+ /* We've not reached the soft limit yet. */
if (deletable_count <= _settings_client.gui.window_soft_limit) break;
assert(last_deletable != NULL);
diff --git a/src/window_func.h b/src/window_func.h
index 604cb1d98..d430c0ccd 100644
--- a/src/window_func.h
+++ b/src/window_func.h
@@ -7,7 +7,7 @@
* See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
*/
-/** @file window_func.h Window functions not directly related to making/drawing windows. */
+/** @file window_func.h %Window functions not directly related to making/drawing windows. */
#ifndef WINDOW_FUNC_H
#define WINDOW_FUNC_H
diff --git a/src/window_type.h b/src/window_type.h
index 921e71dbc..eaf94ac47 100644
--- a/src/window_type.h
+++ b/src/window_type.h
@@ -12,9 +12,7 @@
#ifndef WINDOW_TYPE_H
#define WINDOW_TYPE_H
-/**
- * Window numbers.
- */
+/** %Window numbers. */
enum WindowNumberEnum {
WN_GAME_OPTIONS_AI = 0, ///< AI settings.
WN_GAME_OPTIONS_ABOUT, ///< About window.
@@ -39,33 +37,31 @@ enum WindowNumberEnum {
WN_NETWORK_STATUS_WINDOW_CONTENT_DOWNLOAD, ///< Network content download status.
};
-/**
- * Window classes.
- */
+/** %Window classes. */
enum WindowClass {
WC_NONE, ///< No window, redirects to WC_MAIN_WINDOW.
/**
- * Main window; Window numbers:
+ * Main window; %Window numbers:
* - 0 = #MainWidgets
*/
WC_MAIN_WINDOW = WC_NONE,
/**
- * Main toolbar (the long bar at the top); Window numbers:
+ * Main toolbar (the long bar at the top); %Window numbers:
* - 0 = #ToolbarNormalWidgets
* - 0 = #ToolbarEditorWidgets
*/
WC_MAIN_TOOLBAR,
/**
- * Statusbar (at the bottom of your screen); Window numbers:
+ * Statusbar (at the bottom of your screen); %Window numbers:
* - 0 = #StatusbarWidget
*/
WC_STATUS_BAR,
/**
- * Build toolbar; Window numbers:
+ * Build toolbar; %Window numbers:
* - #TRANSPORT_RAIL = #RailToolbarWidgets
* - #TRANSPORT_AIR = #AirportToolbarWidgets
* - #TRANSPORT_WATER = #DockToolbarWidgets
@@ -74,57 +70,57 @@ enum WindowClass {
WC_BUILD_TOOLBAR,
/**
- * Scenario build toolbar; Window numbers:
+ * Scenario build toolbar; %Window numbers:
* - #TRANSPORT_WATER = #DockToolbarWidgets
* - #TRANSPORT_ROAD = #RoadToolbarWidgets
*/
WC_SCEN_BUILD_TOOLBAR,
/**
- * Build trees toolbar; Window numbers:
+ * Build trees toolbar; %Window numbers:
* - 0 = #BuildTreesWidgets
*/
WC_BUILD_TREES,
/**
- * Transparency toolbar; Window numbers:
+ * Transparency toolbar; %Window numbers:
* - 0 = #TransparencyToolbarWidgets
*/
WC_TRANSPARENCY_TOOLBAR,
/**
- * Build signal toolbar; Window numbers:
+ * Build signal toolbar; %Window numbers:
* - #TRANSPORT_RAIL = #BuildSignalWidgets
*/
WC_BUILD_SIGNAL,
/**
- * Small map; Window numbers:
+ * Small map; %Window numbers:
* - 0 = #SmallMapWidgets
*/
WC_SMALLMAP,
/**
- * Error message; Window numbers:
+ * Error message; %Window numbers:
* - 0 = #ErrorMessageWidgets
*/
WC_ERRMSG,
/**
- * Tooltip window; Window numbers:
+ * Tooltip window; %Window numbers:
* - 0 = #ToolTipsWidgets
*/
WC_TOOLTIPS,
/**
- * Query string window; Window numbers:
+ * Query string window; %Window numbers:
* - #WN_QUERY_STRING = #QueryStringWidgets
* - #WN_QUERY_STRING_SIGN = #QueryEditSignWidgets
*/
WC_QUERY_STRING,
/**
- * Popup with confirm question; Window numbers:
+ * Popup with confirm question; %Window numbers:
* - #WN_CONFIRM_POPUP_QUERY = #QueryWidgets
* - #WN_CONFIRM_POPUP_QUERY_BOOTSTRAP = #BootstrapAskForDownloadWidgets
*/
@@ -132,253 +128,253 @@ enum WindowClass {
/**
- * Saveload window; Window numbers:
+ * Saveload window; %Window numbers:
* - 0 = #SaveLoadWidgets
*/
WC_SAVELOAD,
/**
- * Land info window; Window numbers:
+ * Land info window; %Window numbers:
* - 0 = #LandInfoWidgets
*/
WC_LAND_INFO,
/**
- * Drop down menu; Window numbers:
+ * Drop down menu; %Window numbers:
* - 0 = #DropdownMenuWidgets
*/
WC_DROPDOWN_MENU,
/**
- * On Screen Keyboard; Window numbers:
+ * On Screen Keyboard; %Window numbers:
* - 0 = #OnScreenKeyboardWidgets
*/
WC_OSK,
/**
- * Set date; Window numbers:
+ * Set date; %Window numbers:
* - #VehicleID = #SetDateWidgets
*/
WC_SET_DATE,
/**
- * AI settings; Window numbers:
+ * AI settings; %Window numbers:
* - 0 = #AISettingsWidgets
*/
WC_AI_SETTINGS,
/**
- * NewGRF parameters; Window numbers:
+ * NewGRF parameters; %Window numbers:
* - 0 = #NewGRFParametersWidgets
*/
WC_GRF_PARAMETERS,
/**
- * textfile; Window numbers:
+ * textfile; %Window numbers:
* - 0 = #NewGRFTextfileWidgets
*/
WC_NEWGRF_TEXTFILE,
/**
- * Town authority; Window numbers:
+ * Town authority; %Window numbers:
* - #TownID = #TownAuthorityWidgets
*/
WC_TOWN_AUTHORITY,
/**
- * Vehicle details; Window numbers:
+ * Vehicle details; %Window numbers:
* - #VehicleID = #VehicleDetailsWidgets
*/
WC_VEHICLE_DETAILS,
/**
- * Vehicle refit; Window numbers:
+ * Vehicle refit; %Window numbers:
* - #VehicleID = #VehicleRefitWidgets
*/
WC_VEHICLE_REFIT,
/**
- * Vehicle orders; Window numbers:
+ * Vehicle orders; %Window numbers:
* - #VehicleID = #OrderWidgets
*/
WC_VEHICLE_ORDERS,
/**
- * Replace vehicle window; Window numbers:
+ * Replace vehicle window; %Window numbers:
* - #VehicleType = #ReplaceVehicleWidgets
*/
WC_REPLACE_VEHICLE,
/**
- * Vehicle timetable; Window numbers:
+ * Vehicle timetable; %Window numbers:
* - #VehicleID = #VehicleTimetableWidgets
*/
WC_VEHICLE_TIMETABLE,
/**
- * Company colour selection; Window numbers:
+ * Company colour selection; %Window numbers:
* - #CompanyID = #SelectCompanyLiveryWidgets
*/
WC_COMPANY_COLOUR,
/**
- * Alter company face window; Window numbers:
+ * Alter company face window; %Window numbers:
* - #CompanyID = #SelectCompanyManagerFaceWidgets
*/
WC_COMPANY_MANAGER_FACE,
/**
- * Select station (when joining stations); Window numbers:
+ * Select station (when joining stations); %Window numbers:
* - 0 = #JoinStationWidgets
*/
WC_SELECT_STATION,
/**
- * News window; Window numbers:
+ * News window; %Window numbers:
* - 0 = #NewsWidgets
*/
WC_NEWS_WINDOW,
/**
- * Town directory; Window numbers:
+ * Town directory; %Window numbers:
* - 0 = #TownDirectoryWidgets
*/
WC_TOWN_DIRECTORY,
/**
- * Subsidies list; Window numbers:
+ * Subsidies list; %Window numbers:
* - 0 = #SubsidyListWidgets
*/
WC_SUBSIDIES_LIST,
/**
- * Industry directory; Window numbers:
+ * Industry directory; %Window numbers:
* - 0 = #IndustryDirectoryWidgets
*/
WC_INDUSTRY_DIRECTORY,
/**
- * News history list; Window numbers:
+ * News history list; %Window numbers:
* - 0 = #MessageHistoryWidgets
*/
WC_MESSAGE_HISTORY,
/**
- * Sign list; Window numbers:
+ * Sign list; %Window numbers:
* - 0 = #SignListWidgets
*/
WC_SIGN_LIST,
/**
- * AI list; Window numbers:
+ * AI list; %Window numbers:
* - 0 = #AIListWidgets
*/
WC_AI_LIST,
/**
- * Goals list; Window numbers:
+ * Goals list; %Window numbers:
* - 0 ; #GoalListWidgets
*/
WC_GOALS_LIST,
/**
- * Station list; Window numbers:
+ * Station list; %Window numbers:
* - #CompanyID = #StationListWidgets
*/
WC_STATION_LIST,
/**
- * Trains list; Window numbers:
+ * Trains list; %Window numbers:
* - Packed value = #GroupListWidgets / #VehicleListWidgets
*/
WC_TRAINS_LIST,
/**
- * Road vehicle list; Window numbers:
+ * Road vehicle list; %Window numbers:
* - Packed value = #GroupListWidgets / #VehicleListWidgets
*/
WC_ROADVEH_LIST,
/**
- * Ships list; Window numbers:
+ * Ships list; %Window numbers:
* - Packed value = #GroupListWidgets / #VehicleListWidgets
*/
WC_SHIPS_LIST,
/**
- * Aircraft list; Window numbers:
+ * Aircraft list; %Window numbers:
* - Packed value = #GroupListWidgets / #VehicleListWidgets
*/
WC_AIRCRAFT_LIST,
/**
- * Town view; Window numbers:
+ * Town view; %Window numbers:
* - #TownID = #TownViewWidgets
*/
WC_TOWN_VIEW,
/**
- * Vehicle view; Window numbers:
+ * Vehicle view; %Window numbers:
* - #VehicleID = #VehicleViewWidgets
*/
WC_VEHICLE_VIEW,
/**
- * Station view; Window numbers:
+ * Station view; %Window numbers:
* - #StationID = #StationViewWidgets
*/
WC_STATION_VIEW,
/**
- * Depot view; Window numbers:
+ * Depot view; %Window numbers:
* - #TileIndex = #DepotWidgets
*/
WC_VEHICLE_DEPOT,
/**
- * Waypoint view; Window numbers:
+ * Waypoint view; %Window numbers:
* - #WaypointID = #WaypointWidgets
*/
WC_WAYPOINT_VIEW,
/**
- * Industry view; Window numbers:
+ * Industry view; %Window numbers:
* - #IndustryID = #IndustryViewWidgets
*/
WC_INDUSTRY_VIEW,
/**
- * Company view; Window numbers:
+ * Company view; %Window numbers:
* - #CompanyID = #CompanyWidgets
*/
WC_COMPANY,
/**
- * Build object; Window numbers:
+ * Build object; %Window numbers:
* - 0 = #BuildObjectWidgets
*/
WC_BUILD_OBJECT,
/**
- * Build vehicle; Window numbers:
+ * Build vehicle; %Window numbers:
* - #VehicleType = #BuildVehicleWidgets
* - #TileIndex = #BuildVehicleWidgets
*/
WC_BUILD_VEHICLE,
/**
- * Build bridge; Window numbers:
+ * Build bridge; %Window numbers:
* - #TransportType = #BuildBridgeSelectionWidgets
*/
WC_BUILD_BRIDGE,
/**
- * Build station; Window numbers:
+ * Build station; %Window numbers:
* - #TRANSPORT_AIR = #AirportPickerWidgets
* - #TRANSPORT_WATER = #DockToolbarWidgets
* - #TRANSPORT_RAIL = #BuildRailStationWidgets
@@ -386,19 +382,19 @@ enum WindowClass {
WC_BUILD_STATION,
/**
- * Build bus station; Window numbers:
+ * Build bus station; %Window numbers:
* - #TRANSPORT_ROAD = #BuildRoadStationWidgets
*/
WC_BUS_STATION,
/**
- * Build truck station; Window numbers:
+ * Build truck station; %Window numbers:
* - #TRANSPORT_ROAD = #BuildRoadStationWidgets
*/
WC_TRUCK_STATION,
/**
- * Build depot; Window numbers:
+ * Build depot; %Window numbers:
* - #TRANSPORT_WATER = #BuildDockDepotWidgets
* - #TRANSPORT_RAIL = #BuildRailDepotWidgets
* - #TRANSPORT_ROAD = #BuildRoadDepotWidgets
@@ -406,46 +402,46 @@ enum WindowClass {
WC_BUILD_DEPOT,
/**
- * Build waypoint; Window numbers:
+ * Build waypoint; %Window numbers:
* - #TRANSPORT_RAIL = #BuildRailWaypointWidgets
*/
WC_BUILD_WAYPOINT,
/**
- * Found a town; Window numbers:
+ * Found a town; %Window numbers:
* - 0 = #TownFoundingWidgets
*/
WC_FOUND_TOWN,
/**
- * Build industry; Window numbers:
+ * Build industry; %Window numbers:
* - 0 = #DynamicPlaceIndustriesWidgets
*/
WC_BUILD_INDUSTRY,
/**
- * Select game window; Window numbers:
+ * Select game window; %Window numbers:
* - 0 = #SelectGameIntroWidgets
*/
WC_SELECT_GAME,
/**
- * Landscape generation (in Scenario Editor); Window numbers:
+ * Landscape generation (in Scenario Editor); %Window numbers:
* - 0 = #TerraformToolbarWidgets
* - 0 = #EditorTerraformToolbarWidgets
*/
WC_SCEN_LAND_GEN,
/**
- * Generate landscape (newgame); Window numbers:
+ * Generate landscape (newgame); %Window numbers:
* - GLWM_SCENARIO = #CreateScenarioWidgets
* - #GenenerateLandscapeWindowMode = #GenerateLandscapeWidgets
*/
WC_GENERATE_LANDSCAPE,
/**
- * Progress report of landscape generation; Window numbers:
+ * Progress report of landscape generation; %Window numbers:
* - 0 = #GenerationProgressWidgets
* - 1 = #ScanProgressWidgets
*/
@@ -453,7 +449,7 @@ enum WindowClass {
/**
- * Network window; Window numbers:
+ * Network window; %Window numbers:
* - #WN_NETWORK_WINDOW_GAME = #NetworkGameWidgets
* - #WN_NETWORK_WINDOW_LOBBY = #NetworkLobbyWidgets
* - #WN_NETWORK_WINDOW_CONTENT_LIST = #NetworkContentListWidgets
@@ -462,137 +458,137 @@ enum WindowClass {
WC_NETWORK_WINDOW,
/**
- * Client list; Window numbers:
+ * Client list; %Window numbers:
* - 0 = #ClientListWidgets
*/
WC_CLIENT_LIST,
/**
- * Popup for the client list; Window numbers:
+ * Popup for the client list; %Window numbers:
* - #ClientID = #ClientListPopupWidgets
*/
WC_CLIENT_LIST_POPUP,
/**
- * Network status window; Window numbers:
+ * Network status window; %Window numbers:
* - #WN_NETWORK_STATUS_WINDOW_JOIN = #NetworkJoinStatusWidgets
* - #WN_NETWORK_STATUS_WINDOW_CONTENT_DOWNLOAD = #NetworkContentDownloadStatusWidgets
*/
WC_NETWORK_STATUS_WINDOW,
/**
- * Chatbox; Window numbers:
+ * Chatbox; %Window numbers:
* - #DestType = #NetWorkChatWidgets
*/
WC_SEND_NETWORK_MSG,
/**
- * Company password query; Window numbers:
+ * Company password query; %Window numbers:
* - 0 = #NetworkCompanyPasswordWidgets
*/
WC_COMPANY_PASSWORD_WINDOW,
/**
- * Industry cargoes chain; Window numbers:
+ * Industry cargoes chain; %Window numbers:
* - 0 = #IndustryCargoesWidgets
*/
WC_INDUSTRY_CARGOES,
/**
- * Legend for graphs; Window numbers:
+ * Legend for graphs; %Window numbers:
* - 0 = #GraphLegendWidgets
*/
WC_GRAPH_LEGEND,
/**
- * Finances of a company; Window numbers:
+ * Finances of a company; %Window numbers:
* - #CompanyID = #CompanyWidgets
*/
WC_FINANCES,
/**
- * Income graph; Window numbers:
+ * Income graph; %Window numbers:
* - 0 = #CompanyValueWidgets
*/
WC_INCOME_GRAPH,
/**
- * Operating profit graph; Window numbers:
+ * Operating profit graph; %Window numbers:
* - 0 = #CompanyValueWidgets
*/
WC_OPERATING_PROFIT,
/**
- * Delivered cargo graph; Window numbers:
+ * Delivered cargo graph; %Window numbers:
* - 0 = #CompanyValueWidgets
*/
WC_DELIVERED_CARGO,
/**
- * Performance history graph; Window numbers:
+ * Performance history graph; %Window numbers:
* - 0 = #PerformanceHistoryGraphWidgets
*/
WC_PERFORMANCE_HISTORY,
/**
- * Company value graph; Window numbers:
+ * Company value graph; %Window numbers:
* - 0 = #CompanyValueWidgets
*/
WC_COMPANY_VALUE,
/**
- * Company league window; Window numbers:
+ * Company league window; %Window numbers:
* - 0 = #CompanyLeagueWidgets
*/
WC_COMPANY_LEAGUE,
/**
- * Payment rates graph; Window numbers:
+ * Payment rates graph; %Window numbers:
* - 0 = #CargoPaymentRatesWidgets
*/
WC_PAYMENT_RATES,
/**
- * Performance detail window; Window numbers:
+ * Performance detail window; %Window numbers:
* - 0 = #PerformanceRatingDetailsWidgets
*/
WC_PERFORMANCE_DETAIL,
/**
- * Company infrastructure overview; Window numbers:
+ * Company infrastructure overview; %Window numbers:
* - #CompanyID = #CompanyInfrastructureWidgets
*/
WC_COMPANY_INFRASTRUCTURE,
/**
- * Buyout company (merger); Window numbers:
+ * Buyout company (merger); %Window numbers:
* - #CompanyID = #BuyCompanyWidgets
*/
WC_BUY_COMPANY,
/**
- * Engine preview window; Window numbers:
+ * Engine preview window; %Window numbers:
* - #EngineID = #EnginePreviewWidgets
*/
WC_ENGINE_PREVIEW,
/**
- * Music window; Window numbers:
+ * Music window; %Window numbers:
* - 0 = #MusicWidgets
*/
WC_MUSIC_WINDOW,
/**
- * Music track selection; Window numbers:
+ * Music track selection; %Window numbers:
* - 0 = MusicTrackSelectionWidgets
*/
WC_MUSIC_TRACK_SELECTION,
/**
- * Game options window; Window numbers:
+ * Game options window; %Window numbers:
* - #WN_GAME_OPTIONS_AI = #AIConfigWidgets
* - #WN_GAME_OPTIONS_ABOUT = #AboutWidgets
* - #WN_GAME_OPTIONS_NEWGRF_STATE = #NewGRFStateWidgets
@@ -604,63 +600,63 @@ enum WindowClass {
WC_GAME_OPTIONS,
/**
- * Custom currency; Window numbers:
+ * Custom currency; %Window numbers:
* - 0 = #CustomCurrencyWidgets
*/
WC_CUSTOM_CURRENCY,
/**
- * Cheat window; Window numbers:
+ * Cheat window; %Window numbers:
* - 0 = #CheatWidgets
*/
WC_CHEATS,
/**
- * Extra viewport; Window numbers:
+ * Extra viewport; %Window numbers:
* - Ascending value = #ExtraViewportWidgets
*/
WC_EXTRA_VIEW_PORT,
/**
- * Console; Window numbers:
+ * Console; %Window numbers:
* - 0 = #ConsoleWidgets
*/
WC_CONSOLE,
/**
- * Bootstrap; Window numbers:
+ * Bootstrap; %Window numbers:
* - 0 = #BootstrapBackgroundWidgets
*/
WC_BOOTSTRAP,
/**
- * Highscore; Window numbers:
+ * Highscore; %Window numbers:
* - 0 = #HighscoreWidgets
*/
WC_HIGHSCORE,
/**
- * Endscreen; Window numbers:
+ * Endscreen; %Window numbers:
* - 0 = #HighscoreWidgets
*/
WC_ENDSCREEN,
/**
- * AI debug window; Window numbers:
+ * AI debug window; %Window numbers:
* - 0 = #AIDebugWidgets
*/
WC_AI_DEBUG,
/**
- * NewGRF inspect (debug); Window numbers:
+ * NewGRF inspect (debug); %Window numbers:
* - Packed value = #NewGRFInspectWidgets
*/
WC_NEWGRF_INSPECT,
/**
- * Sprite aligner (debug); Window numbers:
+ * Sprite aligner (debug); %Window numbers:
* - 0 = #SpriteAlignerWidgets
*/
WC_SPRITE_ALIGNER,
@@ -668,9 +664,7 @@ enum WindowClass {
WC_INVALID = 0xFFFF, ///< Invalid window.
};
-/**
- * Data value for #Window::OnInvalidateData() of windows with class #WC_GAME_OPTIONS.
- */
+/** Data value for #Window::OnInvalidateData() of windows with class #WC_GAME_OPTIONS. */
enum GameOptionsInvalidationData {
GOID_DEFAULT = 0,
GOID_NEWGRF_RESCANNED, ///< NewGRFs were just rescanned.