(svn r23704) -Doc: Doxygen comment fixes and additions.

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"

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

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)

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

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

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"

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.
+ * @tparam T Key type.
- * @tvar U Value 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.
+ * @tparam T Key type.
- * @tvar U Value type.
+ * @tparam U Value type.
- * @tvar S Unit of allocation.
+ * @tparam S Unit of allocation.
  *
  * @see SmallVector
  */

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_NOEURO = 0; ///< Currency never switches to the Euro (as far as known).
-static const int CF_ISEURO = 1;
+static const int CF_ISEURO = 1; ///< Currency _is_ the Euro.
-static const uint NUM_CURRENCY = 29;
+static const uint NUM_CURRENCY = 29; ///< Number of currencies.
-static const int CUSTOM_CURRENCY_ID = NUM_CURRENCY - 1;
+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;

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_OR,         ///< '||' within <tt>#if</tt> expression
-	TOKEN_AND,        ///< '&&' within #if expression
+	TOKEN_AND,        ///< '&&' within <tt>#if</tt> expression
-	TOKEN_DEFINED,    ///< 'defined' within #if expression
+	TOKEN_DEFINED,    ///< 'defined' within <tt>#if</tt> expression
-	TOKEN_OPEN,       ///< '(' within #if expression
+	TOKEN_OPEN,       ///< '(' within <tt>#if</tt> expression
-	TOKEN_CLOSE,      ///< ')' within #if expression
+	TOKEN_CLOSE,      ///< ')' within <tt>#if</tt> expression
-	TOKEN_NOT,        ///< '!' within #if expression
+	TOKEN_NOT,        ///< '!' within <tt>#if</tt> expression
-	TOKEN_ZERO,       ///< '0' within #if expression
+	TOKEN_ZERO,       ///< '0' within <tt>#if</tt> expression
 	TOKEN_INCLUDE,    ///< (#)include in code
 };
 

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"

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()
+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_Sort(GUIEngineList *el, EngList_SortTypeFunction compare);
-void EngList_SortPartial(GUIEngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items); ///< sort of specified portion of the engine list
+void EngList_SortPartial(GUIEngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items);
 
 StringID GetEngineCategoryName(EngineID engine);
 StringID GetEngineInfoString(EngineID engine);

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_DIR,        ///< Subdirectory for all %AI files
-	AI_LIBRARY_DIR,///< Subdirectory for all AI libraries
+	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

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

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;
 }

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

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
+ * @pre \c *t != NULL
- * @postcon \c *t points to a town on success, and \c NULL on failure.
+ * @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. */

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

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
+	bool enabled;                          ///< Entity still available (by default true). Newgrf can disable it, though.
-	struct GRFFileProps grf_prop;          ///< properties related the the grf file
+	struct GRFFileProps grf_prop;          ///< Properties related to the grf file.
 
 	static const AirportSpec *Get(byte type);
 	static AirportSpec *GetWithoutOverride(byte type);

src/newgrf_commons.cpp

@@ -8,8 +8,8 @@
  */
 
 /**
- * @file newgrf_commons.cpp Implementation of the class OverrideManagerBase
+ * @file newgrf_commons.cpp Implementation of the class %OverrideManagerBase
- * and its descendance, present and futur
+ * and its descendance, present and future.
  */
 
 #include "stdafx.h"

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)
 {

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.
+ * On #ClearChanges that data is either reverted or saved.
- * @param TYPE the type of variable to store.
+ * @tparam TYPE the type of variable to store.
- * @param SIZE the size of the array.
+ * @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.
+ * On #ClearChanges that data is always zero-ed.
- * @param TYPE the type of variable to store.
+ * @tparam TYPE the type of variable to store.
- * @param SIZE the size of the array.
+ * @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".

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)

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

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.
+	/* Add prefix part, following symbol_pos specification.
-	 * Here, it can can be either 0 (prefix) or 2 (both prefix anf suffix).
+	 * 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.
+	/* Add suffix part, following symbol_pos specification.
-	 * Here, it can can be either 1 (suffix) or 2 (both prefix anf suffix).
+	 * 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
+ * Make a list of the available language packs. Put the data in
- * _dynlang struct.
+ * #_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;

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;

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

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

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"

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

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
+ * Try to find a depot nearby.
- * crashed!
+ * @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 small_turn; ///< Speed change due to a small turn.
-	byte z_up; // fraction to remove when moving up
+	byte large_turn; ///< Speed change due to a large turn.
-	byte z_down; // fraction to remove when moving down
+	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
+	Train *v; ///< %Vehicle we are testing for collision.
-	uint num; ///< number of victims if train collided
+	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;

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.
 	 */

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"
 

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)
 {

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
+ * @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
+ * @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);

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

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.