(svn r20283) -Codechange: Unify start of doygen comments.

11 files changed, 74 insertions, 37 deletions

diff --git a/src/table/airporttiles.h b/src/table/airporttiles.h
index 00139478a..06a880df0 100644
--- a/src/table/airporttiles.h
+++ b/src/table/airporttiles.h
@@ -17,7 +17,8 @@
 /** Writes an airport tile without animation in the AirportTile struct */
 #define AT_NOANIM {0xFFFF, 2, STR_NULL, 0, 0, 0, true, {INVALID_AIRPORTTILE, 0, NULL, NULL, INVALID_AIRPORTTILE}}
 
-/** All default airport tiles.
+/**
+ * All default airport tiles.
  * @see AirportTiles for a list of names. */
 static const AirportTileSpec _origin_airporttile_specs[] = {
 	/* 0..9 */
diff --git a/src/table/animcursors.h b/src/table/animcursors.h
index f0b538beb..4757c5c53 100644
--- a/src/table/animcursors.h
+++ b/src/table/animcursors.h
@@ -7,7 +7,8 @@
  * 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 animcursors.h
+/**
+ * @file animcursors.h
  * This file defines all the the animated cursors.
  * Animated cursors consist of the number of sprites that are
  * displayed in a round-robin manner. Each sprite also has a time
@@ -15,18 +16,21 @@
  * is to be displayed.
  */
 
-/** Creates two array entries that define one
+/**
+ * Creates two array entries that define one
  *  status of the cursor.
  *  @param Sprite The Sprite to be displayed
  *  @param display_time The Number of ticks to display the sprite
  */
 #define ANIM_CURSOR_LINE(Sprite, display_time) { Sprite, display_time },
 
-/** This indicates the termination of the cursor list
+/**
+ * This indicates the termination of the cursor list
  */
 #define ANIM_CURSOR_END() ANIM_CURSOR_LINE(AnimCursor::LAST, 0)
 
-/** Animated cursor elements for demolishion
+/**
+ * Animated cursor elements for demolishion
  */
 static const AnimCursor _demolish_animcursor[] = {
 	ANIM_CURSOR_LINE(0x2C0, 8)
@@ -36,7 +40,8 @@ static const AnimCursor _demolish_animcursor[] = {
 	ANIM_CURSOR_END()
 };
 
-/** Animated cursor elements for lower land
+/**
+ * Animated cursor elements for lower land
  */
 static const AnimCursor _lower_land_animcursor[] = {
 	ANIM_CURSOR_LINE(0x2BB, 10)
@@ -45,7 +50,8 @@ static const AnimCursor _lower_land_animcursor[] = {
 	ANIM_CURSOR_END()
 };
 
-/** Animated cursor elements for raise land
+/**
+ * Animated cursor elements for raise land
  */
 static const AnimCursor _raise_land_animcursor[] = {
 	ANIM_CURSOR_LINE(0x2B8, 10)
@@ -54,7 +60,8 @@ static const AnimCursor _raise_land_animcursor[] = {
 	ANIM_CURSOR_END()
 };
 
-/** Animated cursor elements for the goto icon
+/**
+ * Animated cursor elements for the goto icon
  */
 static const AnimCursor _order_goto_animcursor[] = {
 	ANIM_CURSOR_LINE(0x2CC, 10)
@@ -63,7 +70,8 @@ static const AnimCursor _order_goto_animcursor[] = {
 	ANIM_CURSOR_END()
 };
 
-/** Animated cursor elements for the build signal icon
+/**
+ * Animated cursor elements for the build signal icon
  */
 static const AnimCursor _build_signals_animcursor[] = {
 	ANIM_CURSOR_LINE(0x50C, 20)
@@ -71,7 +79,8 @@ static const AnimCursor _build_signals_animcursor[] = {
 	ANIM_CURSOR_END()
 };
 
-/** This is an array of pointers to all the animated cursor
+/**
+ * This is an array of pointers to all the animated cursor
  *  definitions we have above. This is the only thing that is
  *  accessed directly from other files
  */
diff --git a/src/table/bridge_land.h b/src/table/bridge_land.h
index f5a2b7638..d1c6fefc5 100644
--- a/src/table/bridge_land.h
+++ b/src/table/bridge_land.h
@@ -7,7 +7,8 @@
  * 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 bridge_land.h This file contains all the sprites for bridges
+/**
+ * @file bridge_land.h This file contains all the sprites for bridges
  * It consists of a number of arrays.
  * <ul><li>_bridge_sprite_table_n_m. Defines all the sprites of a bridge besides the pylons.
  * n defines the number of the bridge type, m the number of the section. the highest m for
@@ -726,7 +727,8 @@ static const PalSpriteID * const * const _bridge_sprite_table[MAX_BRIDGES] = {
 	_bridge_sprite_table_12
 };
 
-/** Describes the data that defines each bridge in the game
+/**
+ * Describes the data that defines each bridge in the game
  * @param y   year of availablity
  * @param mnl minimum length (not counting bridge heads)
  * @param mxl maximum length (not counting bridge heads)
diff --git a/src/table/build_industry.h b/src/table/build_industry.h
index 99165df37..b5aa117fe 100644
--- a/src/table/build_industry.h
+++ b/src/table/build_industry.h
@@ -1568,7 +1568,8 @@ static const IndustrySpec _origin_industry_specs[NEW_INDUSTRYOFFSET] = {
 };
 #undef MI
 
-/** Writes the properties of an industry tile into the IndustryTileSpec struct.
+/**
+ * Writes the properties of an industry tile into the IndustryTileSpec struct.
  * @param ca1 acceptance of first cargo
  * @param c1  first type of cargo accepted for this tile
  * @param ca2 acceptance of second cargo
diff --git a/src/table/elrail_data.h b/src/table/elrail_data.h
index 4c008a773..2863db781 100644
--- a/src/table/elrail_data.h
+++ b/src/table/elrail_data.h
@@ -7,13 +7,15 @@
  * 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 elrail_data.h Stores all the data for overhead wire and pylon drawing.
+/**
+ * @file elrail_data.h Stores all the data for overhead wire and pylon drawing.
  *  @see elrail.c */
 
 #ifndef ELRAIL_DATA_H
 #define ELRAIL_DATA_H
 
-/** Tile Location group.
+/**
+ * Tile Location group.
  * This defines whether the X and or Y coordinate of a tile is even */
 enum TLG {
 	XEVEN_YEVEN = 0,
@@ -23,7 +25,8 @@ enum TLG {
 	TLG_END
 };
 
-/** When determining the pylon configuration on the edge, two tiles are taken
+/**
+ * When determining the pylon configuration on the edge, two tiles are taken
  * into account: the tile being drawn itself (the home tile, the one in
  * ti->tile), and the neighbouring tile */
 enum TileSource {
@@ -43,7 +46,8 @@ static const byte AllowedPPPonPCP[DIAGDIR_END] = {
 	1 << DIR_N | 1 << DIR_NE | 1 << DIR_E  | 1 << DIR_S | 1 << DIR_SW | 1 << DIR_W,
 };
 
-/** Which of the PPPs are inside the tile. For the two PPPs on the tile border
+/**
+ * Which of the PPPs are inside the tile. For the two PPPs on the tile border
  * the following system is used: if you rotate the PCP so that it is in the
  * north, the eastern PPP belongs to the tile. */
 static const byte OwnedPPPonPCP[DIAGDIR_END] = {
@@ -64,7 +68,8 @@ static const DiagDirection PCPpositions[TRACK_END][2] = {
 };
 
 #define PCP_NOT_ON_TRACK 0xFF
-/** Preferred points of each trackbit. Those are the ones perpendicular to the
+/**
+ * Preferred points of each trackbit. Those are the ones perpendicular to the
  * track, plus the point in extension of the track (to mark end-of-track). PCPs
  * which are not on either end of the track are fully preferred.
  * @see PCPpositions */
@@ -106,7 +111,8 @@ static const byte PreferredPPPofTrackAtPCP[TRACK_END][DIAGDIR_END] = {
 
 #define NUM_IGNORE_GROUPS 3
 #define IGNORE_NONE 0xFF
-/** In case we have a staight line, we place pylon only every two tiles,
+/**
+ * In case we have a staight line, we place pylon only every two tiles,
  * so there are certain tiles which we ignore. A straight line is found if
  * we have exactly two PPPs. */
 static const byte IgnoredPCP[NUM_IGNORE_GROUPS][TLG_END][DIAGDIR_END] = {
@@ -395,7 +401,8 @@ static const SortableSpriteStruct CatenarySpriteData_Tunnel[] = {
 };
 
 
-/** Refers to a certain element of the catenary.
+/**
+ * Refers to a certain element of the catenary.
  * Identifiers for Wires:
  * <ol><li>Direction of the wire</li>
  * <li>Slope of the tile for diagonals, placement inside the track for horiz/vertical pieces</li>
diff --git a/src/table/engines.h b/src/table/engines.h
index 8e7d9da85..ffd29d777 100644
--- a/src/table/engines.h
+++ b/src/table/engines.h
@@ -7,14 +7,16 @@
  * 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 table/engines.h
+/**
+ * @file table/engines.h
  *  This file contains all the data for vehicles
  */
 
 #ifndef ENGINES_H
 #define ENGINES_H
 
-/** Writes the properties of a train or road vehicle into the EngineInfo struct.
+/**
+ * Writes the properties of a train or road vehicle into the EngineInfo struct.
  * @see EngineInfo
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
@@ -27,7 +29,8 @@
  */
 #define MK(a, b, c, d, e, f) { DAYS_TILL_ORIGINAL_BASE_YEAR + a, c, d, b, 5, f, e, 0, 8, 0, 0, 0, STR_EMPTY }
 
-/** Writes the properties of a train carriage into the EngineInfo struct.
+/**
+ * Writes the properties of a train carriage into the EngineInfo struct.
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
@@ -39,7 +42,8 @@
  */
 #define MW(a, b, c, d, e, f) { DAYS_TILL_ORIGINAL_BASE_YEAR + a, c, d, b, 5, f, e, 0, 8, 0, 0, 0, STR_EMPTY }
 
-/** Writes the properties of a ship into the EngineInfo struct.
+/**
+ * Writes the properties of a ship into the EngineInfo struct.
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
@@ -51,7 +55,8 @@
  */
 #define MS(a, b, c, d, e, f) { DAYS_TILL_ORIGINAL_BASE_YEAR + a, c, d, b, 10, f, e, 0, 8, 0, 0, 0, STR_EMPTY }
 
-/** Writes the properties of an aeroplane into the EngineInfo struct.
+/**
+ * Writes the properties of an aeroplane into the EngineInfo struct.
  * @param a base introduction date (days since 1920-01-01)
  * @param b decay speed
  * @param c life length (years)
@@ -342,7 +347,8 @@ static const EngineInfo _orig_engine_info[] = {
 #undef MS
 #undef MA
 
-/** Writes the properties of a rail vehicle into the RailVehicleInfo struct.
+/**
+ * Writes the properties of a rail vehicle into the RailVehicleInfo struct.
  * @see RailVehicleInfo
  * @param a image_index
  * @param b type
@@ -523,7 +529,8 @@ static const RailVehicleInfo _orig_rail_vehicle_info[] = {
 #undef M
 #undef RVI
 
-/** Writes the properties of a ship into the ShipVehicleInfo struct.
+/**
+ * Writes the properties of a ship into the ShipVehicleInfo struct.
  * @see ShipVehicleInfo
  * @param a image_index
  * @param b cost_factor
@@ -553,7 +560,8 @@ static const ShipVehicleInfo _orig_ship_vehicle_info[] = {
 };
 #undef SVI
 
-/** Writes the properties of an aircraft into the AircraftVehicleInfo struct.
+/**
+ * Writes the properties of an aircraft into the AircraftVehicleInfo struct.
  * @see AircraftVehicleInfo
  * @param a image_index
  * @param b cost_factor
@@ -622,7 +630,8 @@ static const AircraftVehicleInfo _orig_aircraft_vehicle_info[] = {
 #undef H
 #undef AVI
 
-/** Writes the properties of a road vehicle into the RoadVehicleInfo struct.
+/**
+ * Writes the properties of a road vehicle into the RoadVehicleInfo struct.
  * @see RoadVehicleInfo
  * @param a image_index
  * @param b cost_factor
diff --git a/src/table/industry_land.h b/src/table/industry_land.h
index 561c116cc..fae7a7b8e 100644
--- a/src/table/industry_land.h
+++ b/src/table/industry_land.h
@@ -862,7 +862,8 @@ static const DrawIndustryCoordinates _drawtile_proc1[5] = {
 	{ 8, 41},
 };
 
-/** this is ONLY used for Toy Factory.
+/**
+ * this is ONLY used for Toy Factory.
  * 255 means no drawing
  * @param img1 offset from base sprite SPR_IT_SUGAR_MINE_SIEVE
  * @param img2 offset from base sprite SPR_IT_SUGAR_MINE_CLOUDS
diff --git a/src/table/railtypes.h b/src/table/railtypes.h
index d70e22954..eda7e6ff0 100644
--- a/src/table/railtypes.h
+++ b/src/table/railtypes.h
@@ -7,14 +7,16 @@
  * 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 railtypes.h
+/**
+ * @file railtypes.h
  * All the railtype-specific information is stored here.
  */
 
 #ifndef RAILTYPES_H
 #define RAILTYPES_H
 
-/** Global Railtype definition
+/**
+ * Global Railtype definition
  */
 static const RailtypeInfo _original_railtypes[] = {
 	/** Railway */
diff --git a/src/table/settings.h b/src/table/settings.h
index 255c7055e..8533f8f25 100644
--- a/src/table/settings.h
+++ b/src/table/settings.h
@@ -53,7 +53,8 @@ static bool UpdateClientConfigValues(int32 p1);
  * OTTD specific INI stuff
  ****************************/
 
-/** Settings-macro usage:
+/**
+ * Settings-macro usage:
  * The list might look daunting at first, but is in general easy to understand.
  * We have two types of list:
  * 1. SDTG_something
diff --git a/src/table/sprites.h b/src/table/sprites.h
index 2334a9c68..e5639099d 100644
--- a/src/table/sprites.h
+++ b/src/table/sprites.h
@@ -7,7 +7,8 @@
  * 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 sprites.h
+/**
+ * @file sprites.h
  * This file contails all sprite-related enums and defines. These consist mainly of
  * the sprite numbers and a bunch of masks and macros to handle sprites and to get
  * rid of all the magic numbers in the code.
@@ -1451,7 +1452,8 @@ enum Modifiers {
 	PALETTE_MODIFIER_COLOUR       = RECOLOUR_BIT,
 };
 
-/** Masks needed for sprite operations.
+/**
+ * Masks needed for sprite operations.
  * @note Do not modify this enum. Alter SpriteSetup instead
  * @see SpriteSetup */
 enum SpriteMasks {
diff --git a/src/table/town_land.h b/src/table/town_land.h
index bb0915691..2055cfb26 100644
--- a/src/table/town_land.h
+++ b/src/table/town_land.h
@@ -9,7 +9,8 @@
 
 /** @file town_land.h Sprites to use and how to display them for town tiles. */
 
-/** Writes the data into the Town Tile Drawing Struct
+/**
+ * Writes the data into the Town Tile Drawing Struct
  * @param s1 The first sprite of the building, mostly the ground sprite
  * @param p1 The first sprite's palette of the building, mostly the ground sprite
  * @param s2 The second sprite of the building.
@@ -1790,7 +1791,8 @@ static const DrawBuildingsTileStruct _town_draw_tile_data[] = {
 /** Make sure we have the right number of elements: 4 variants * 4 build stages for each house */
 assert_compile(lengthof(_town_draw_tile_data) == (NEW_HOUSE_OFFSET) * 4 * 4);
 
-/** Describes the data that defines each house in the game
+/**
+ * Describes the data that defines each house in the game
  * @param mnd introduction year of the house
  * @param mxd last year it can be built
  * @param p   population