(svn r14491) -Documentation: updates/additions of doxygen docs (Alberth)

15 files changed, 191 insertions, 77 deletions

diff --git a/src/cargo_type.h b/src/cargo_type.h
index afdacdac0..57365857d 100644
--- a/src/cargo_type.h
+++ b/src/cargo_type.h
@@ -7,7 +7,8 @@
 
 typedef byte CargoID;
 
-enum {
+/** Available types of cargo */
+enum CargoTypes {
 	/* Temperate */
 	CT_PASSENGERS   =  0,
 	CT_COAL         =  1,
@@ -54,6 +55,7 @@ enum {
 	CT_INVALID      = 0xFF
 };
 
+/** Array for storing amounts of accepted cargo */
 typedef uint AcceptedCargo[NUM_CARGO];
 
-#endif /* OPENTTD_H */
+#endif /* CARGO_TYPE_H */
diff --git a/src/landscape.cpp b/src/landscape.cpp
index 2277bdff0..fd71cd7ec 100644
--- a/src/landscape.cpp
+++ b/src/landscape.cpp
@@ -2,6 +2,8 @@
 
 /** @file landscape.cpp Functions related to the landscape (slopes etc.). */
 
+/** @defgroup SnowLineGroup Snowline functions and data structures */
+
 #include "stdafx.h"
 #include "openttd.h"
 #include "bridge_map.h"
@@ -44,18 +46,21 @@ extern const TileTypeProcs
 	_tile_type_tunnelbridge_procs,
 	_tile_type_unmovable_procs;
 
+/** Tile callback functions for each type of tile.
+ * @ingroup TileCallbackGroup
+ * @see TileType */
 const TileTypeProcs * const _tile_type_procs[16] = {
-	&_tile_type_clear_procs,
-	&_tile_type_rail_procs,
-	&_tile_type_road_procs,
-	&_tile_type_town_procs,
-	&_tile_type_trees_procs,
-	&_tile_type_station_procs,
-	&_tile_type_water_procs,
-	&_tile_type_dummy_procs,
-	&_tile_type_industry_procs,
-	&_tile_type_tunnelbridge_procs,
-	&_tile_type_unmovable_procs,
+	&_tile_type_clear_procs,        ///< Callback functions for MP_CLEAR tiles
+	&_tile_type_rail_procs,         ///< Callback functions for MP_RAILWAY tiles
+	&_tile_type_road_procs,         ///< Callback functions for MP_ROAD tiles
+	&_tile_type_town_procs,         ///< Callback functions for MP_HOUSE tiles
+	&_tile_type_trees_procs,        ///< Callback functions for MP_TREES tiles
+	&_tile_type_station_procs,      ///< Callback functions for MP_STATION tiles
+	&_tile_type_water_procs,        ///< Callback functions for MP_WATER tiles
+	&_tile_type_dummy_procs,        ///< Callback functions for MP_VOID tiles
+	&_tile_type_industry_procs,     ///< Callback functions for MP_INDUSTRY tiles
+	&_tile_type_tunnelbridge_procs, ///< Callback functions for MP_TUNNELBRIDGE tiles
+	&_tile_type_unmovable_procs,    ///< Callback functions for MP_UNMOVABLE tiles
 };
 
 /* landscape slope => sprite */
@@ -64,6 +69,13 @@ const byte _tileh_to_sprite[32] = {
 	0, 0, 0, 0, 0, 0, 0, 16, 0, 0,  0, 17,  0, 15, 18, 0,
 };
 
+/**
+ * Description of the snow line throughout the year.
+ *
+ * If it is \c NULL, a static snowline height is used, as set by \c _settings_game.game_creation.snow_line.
+ * Otherwise it points to a table loaded from a newGRF file, that describes the variable snowline
+ * @ingroup SnowLineGroup
+ * @see GetSnowLine() GameCreationSettings */
 SnowLine *_snow_line = NULL;
 
 /**
@@ -360,7 +372,11 @@ static bool HasFoundationNE(TileIndex tile, Slope slope_here, uint z_here)
 	return (z_N_here > z_N) || (z_E_here > z_E);
 }
 
-
+/**
+ * Draw foundation \a f at tile \a ti. Updates \a ti.
+ * @param ti Tile to draw foundation on
+ * @param f  Foundation to draw
+ */
 void DrawFoundation(TileInfo *ti, Foundation f)
 {
 	if (!IsFoundation(f)) return;
@@ -508,6 +524,7 @@ void GetTileDesc(TileIndex tile, TileDesc *td)
 /**
  * Has a snow line table already been loaded.
  * @return true if the table has been loaded already.
+ * @ingroup SnowLineGroup
  */
 bool IsSnowLineSet(void)
 {
@@ -517,6 +534,7 @@ bool IsSnowLineSet(void)
 /**
  * Set a variable snow line, as loaded from a newgrf file.
  * @param table the 12 * 32 byte table containing the snowline for each day
+ * @ingroup SnowLineGroup
  */
 void SetSnowLine(byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS])
 {
@@ -533,6 +551,7 @@ void SetSnowLine(byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS])
 /**
  * Get the current snow line, either variable or static.
  * @return the snow line height.
+ * @ingroup SnowLineGroup
  */
 byte GetSnowLine(void)
 {
@@ -546,6 +565,7 @@ byte GetSnowLine(void)
 /**
  * Get the highest possible snow line height, either variable or static.
  * @return the highest snow line height.
+ * @ingroup SnowLineGroup
  */
 byte HighestSnowLine(void)
 {
@@ -554,6 +574,7 @@ byte HighestSnowLine(void)
 
 /**
  * Clear the variable snow line table and free the memory.
+ * @ingroup SnowLineGroup
  */
 void ClearSnowLine(void)
 {
diff --git a/src/landscape.h b/src/landscape.h
index 4e2db7735..79edaec6b 100644
--- a/src/landscape.h
+++ b/src/landscape.h
@@ -11,13 +11,15 @@
 #include "direction_type.h"
 
 enum {
-	SNOW_LINE_MONTHS = 12,
-	SNOW_LINE_DAYS   = 32,
+	SNOW_LINE_MONTHS = 12, ///< Number of months in the snow line table.
+	SNOW_LINE_DAYS   = 32, ///< Number of days in each month in the snow line table.
 };
 
+/** Structure describing the height of the snow line each day of the year
+ * @ingroup SnowLineGroup */
 struct SnowLine {
-	byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS];
-	byte highest_value;
+	byte table[SNOW_LINE_MONTHS][SNOW_LINE_DAYS]; ///< Height of the snow line each day of the year
+	byte highest_value; ///< Highest snow line of the year
 };
 
 bool IsSnowLineSet(void);
diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp
index 61beff3bf..e7c9956ab 100644
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -2468,7 +2468,8 @@ int TicksToLeaveDepot(const Vehicle *v)
 	return 0; // make compilers happy
 }
 
-
+/** Tile callback routine when vehicle enters tile
+ * @see vehicle_enter_tile_proc */
 static VehicleEnterTileStatus VehicleEnter_Track(Vehicle *v, TileIndex tile, int x, int y)
 {
 	byte fract_coord;
diff --git a/src/road_cmd.cpp b/src/road_cmd.cpp
index 082a6e953..02c1ed6b2 100644
--- a/src/road_cmd.cpp
+++ b/src/road_cmd.cpp
@@ -43,7 +43,10 @@
 #include "table/sprites.h"
 #include "table/strings.h"
 
-
+/**
+ * Verify whether a road vehicle is available.
+ * @return \c true if at least one road vehicle is available, \c false if not
+ */
 bool RoadVehiclesAreBuilt()
 {
 	const Vehicle* v;
@@ -1156,6 +1159,7 @@ static void DrawRoadBits(TileInfo *ti)
 	}
 }
 
+/** Tile callback function for rendering a road tile to the screen */
 static void DrawTile_Road(TileInfo *ti)
 {
 	switch (GetRoadTileType(ti->tile)) {
@@ -1630,20 +1634,20 @@ static CommandCost TerraformTile_Road(TileIndex tile, uint32 flags, uint z_new,
 	return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 }
 
-
+/** Tile callback functions for road tiles */
 extern const TileTypeProcs _tile_type_road_procs = {
-	DrawTile_Road,           /* draw_tile_proc */
-	GetSlopeZ_Road,          /* get_slope_z_proc */
-	ClearTile_Road,          /* clear_tile_proc */
-	GetAcceptedCargo_Road,   /* get_accepted_cargo_proc */
-	GetTileDesc_Road,        /* get_tile_desc_proc */
-	GetTileTrackStatus_Road, /* get_tile_track_status_proc */
-	ClickTile_Road,          /* click_tile_proc */
-	AnimateTile_Road,        /* animate_tile_proc */
-	TileLoop_Road,           /* tile_loop_clear */
-	ChangeTileOwner_Road,    /* change_tile_owner_clear */
-	NULL,                    /* get_produced_cargo_proc */
-	VehicleEnter_Road,       /* vehicle_enter_tile_proc */
-	GetFoundation_Road,      /* get_foundation_proc */
-	TerraformTile_Road,      /* terraform_tile_proc */
+	DrawTile_Road,           // draw_tile_proc
+	GetSlopeZ_Road,          // get_slope_z_proc
+	ClearTile_Road,          // clear_tile_proc
+	GetAcceptedCargo_Road,   // get_accepted_cargo_proc
+	GetTileDesc_Road,        // get_tile_desc_proc
+	GetTileTrackStatus_Road, // get_tile_track_status_proc
+	ClickTile_Road,          // click_tile_proc
+	AnimateTile_Road,        // animate_tile_proc
+	TileLoop_Road,           // tile_loop_clear
+	ChangeTileOwner_Road,    // change_tile_owner_clear
+	NULL,                    // get_produced_cargo_proc
+	VehicleEnter_Road,       // vehicle_enter_tile_proc
+	GetFoundation_Road,      // get_foundation_proc
+	TerraformTile_Road,      // terraform_tile_proc
 };
diff --git a/src/station.cpp b/src/station.cpp
index 97ad6c712..128dbe9b7 100644
--- a/src/station.cpp
+++ b/src/station.cpp
@@ -321,6 +321,15 @@ bool StationRect::BeforeAddRect(TileIndex tile, int w, int h, StationRectMode mo
 			BeforeAddTile(tile, mode) && BeforeAddTile(TILE_ADDXY(tile, w - 1, h - 1), mode);
 }
 
+/**
+ * Check whether station tiles of the given station id exist in the given rectangle
+ * @param st_id    Station ID to look for in the rectangle
+ * @param left_a   Minimal tile X edge of the rectangle
+ * @param top_a    Minimal tile Y edge of the rectangle
+ * @param right_a  Maximal tile X edge of the rectangle (inclusive)
+ * @param bottom_a Maximal tile Y edge of the rectangle (inclusive)
+ * @return \c true if a station tile with the given \a st_id exists in the rectangle, \c false otherwise
+ */
 /*static*/ bool StationRect::ScanForStationTiles(StationID st_id, int left_a, int top_a, int right_a, int bottom_a)
 {
 	TileIndex top_left = TileXY(left_a, top_a);
diff --git a/src/station_base.h b/src/station_base.h
index 4bdc9270c..0a0019af2 100644
--- a/src/station_base.h
+++ b/src/station_base.h
@@ -107,6 +107,7 @@ struct StationRect : public Rect {
 	StationRect& operator = (Rect src);
 };
 
+/** Station data structure */
 struct Station : PoolItem<Station, StationID, &_Station_pool> {
 public:
 	RoadStop *GetPrimaryRoadStop(RoadStopType type) const
@@ -150,13 +151,13 @@ public:
 	uint8 num_specs;
 	StationSpecList *speclist;
 
-	Date build_date;
+	Date build_date;  ///< Date of construction
 
 	uint64 airport_flags;   ///< stores which blocks on the airport are taken. was 16 bit earlier on, then 32
 
 	byte last_vehicle_type;
 	std::list<Vehicle *> loading_vehicles;
-	GoodsEntry goods[NUM_CARGO];
+	GoodsEntry goods[NUM_CARGO];  ///< Goods at this station
 
 	uint16 random_bits;
 	byte waiting_triggers;
diff --git a/src/station_map.h b/src/station_map.h
index 0f3ff0721..c7d938f3d 100644
--- a/src/station_map.h
+++ b/src/station_map.h
@@ -14,6 +14,10 @@
 
 typedef byte StationGfx;
 
+/** Get Station ID from a tile
+ * @pre Tile \t must be part of the station
+ * @param t Tile to query station ID from
+ * @return Station ID of the station at \a t */
 static inline StationID GetStationIndex(TileIndex t)
 {
 	assert(IsTileType(t, MP_STATION));
@@ -97,16 +101,29 @@ static inline bool IsAirport(TileIndex t)
 
 bool IsHangar(TileIndex t);
 
+/**
+ * Is the station at \a t a truck stop?
+ * @param t Tile to check
+ * @return \c true if station is a truck stop, \c false otherwise */
 static inline bool IsTruckStop(TileIndex t)
 {
 	return GetStationType(t) == STATION_TRUCK;
 }
 
+/**
+ * Is the station at \a t a bus stop?
+ * @param t Tile to check
+ * @return \c true if station is a bus stop, \c false otherwise */
 static inline bool IsBusStop(TileIndex t)
 {
 	return GetStationType(t) == STATION_BUS;
 }
 
+/**
+ * Is the station at \a t a road station?
+ * @pre Tile at \a t is a station tile
+ * @param t Tile to check
+ * @return \c true if station at the tile is a bus top or a truck stop, \c false otherwise */
 static inline bool IsRoadStop(TileIndex t)
 {
 	assert(IsTileType(t, MP_STATION));
diff --git a/src/station_type.h b/src/station_type.h
index 85457d544..854746b0b 100644
--- a/src/station_type.h
+++ b/src/station_type.h
@@ -14,6 +14,7 @@ struct StationSpec;
 
 static const StationID INVALID_STATION = 0xFFFF;
 
+/** Station types */
 enum StationType {
 	STATION_RAIL,
 	STATION_AIRPORT,
diff --git a/src/tile_cmd.h b/src/tile_cmd.h
index d106d5d79..a3be7ea44 100644
--- a/src/tile_cmd.h
+++ b/src/tile_cmd.h
@@ -39,34 +39,53 @@ enum VehicleEnterTileStatus {
 };
 DECLARE_ENUM_AS_BIT_SET(VehicleEnterTileStatus);
 
+/** Tile information, used while rendering the tile */
 struct TileInfo {
-	uint x;
-	uint y;
-	Slope tileh;
-	TileIndex tile;
-	uint z;
+	uint x;         ///< X position of the tile in unit coordinates
+	uint y;         ///< Y position of the tile in unit coordinates
+	Slope tileh;    ///< Slope of the tile
+	TileIndex tile; ///< Tile index
+	uint z;         ///< Height
 };
 
+/** Tile description for the 'land area information' tool */
 struct TileDesc {
-	StringID str;
-	Owner owner[4];
-	StringID owner_type[4];
-	Date build_date;
-	StringID station_class;
-	StringID station_name;
-	const char *grf;
-	uint64 dparam[2];
+	StringID str;           ///< Description of the tile
+	Owner owner[4];         ///< Name of the owner(s)
+	StringID owner_type[4]; ///< Type of each owner
+	Date build_date;        ///< Date of construction of tile contents
+	StringID station_class; ///< Class of station
+	StringID station_name;  ///< Type of station within the class
+	const char *grf;        ///< newGRF used for the tile contents
+	uint64 dparam[2];       ///< Parameters of the \a str string
 };
 
+/**
+ * Tile callback function signature for drawing a tile and its contents to the screen
+ * @param ti Information about the tile to draw
+ */
 typedef void DrawTileProc(TileInfo *ti);
 typedef uint GetSlopeZProc(TileIndex tile, uint x, uint y);
 typedef CommandCost ClearTileProc(TileIndex tile, byte flags);
+
+/**
+ * Tile callback function signature for obtaining accepted carog of a tile
+ * @param tile Tile queried for its accepted cargo
+ * @param res  Storage destination of the cargo accepted
+ */
 typedef void GetAcceptedCargoProc(TileIndex tile, AcceptedCargo res);
+
+/**
+ * Tile callback function signature for obtaining a tile description
+ * @param tile Tile being queried
+ * @param td   Storage pointer for returned tile description
+ */
 typedef void GetTileDescProc(TileIndex tile, TileDesc *td);
 
 /**
- * GetTileTrackStatusProcs return a value that contains the possible tracks
+ * Tile callback function signature for getting the possible tracks
  * that can be taken on a given tile by a given transport.
+ *
  * The return value contains the existing trackdirs and signal states.
  *
  * see track_func.h for usage of TrackStatus.
@@ -77,6 +96,12 @@ typedef void GetTileDescProc(TileIndex tile, TileDesc *td);
  * @return the track status information
  */
 typedef TrackStatus GetTileTrackStatusProc(TileIndex tile, TransportType mode, uint sub_mode, DiagDirection side);
+
+/**
+ * Tile callback function signature for obtaining the produced cargo of a tile.
+ * @param tile Tile being queried
+ * @param b    Destination array of produced cargo
+ */
 typedef void GetProducedCargoProc(TileIndex tile, CargoID *b);
 typedef void ClickTileProc(TileIndex tile);
 typedef void AnimateTileProc(TileIndex tile);
@@ -88,9 +113,11 @@ typedef VehicleEnterTileStatus VehicleEnterTileProc(Vehicle *v, TileIndex tile,
 typedef Foundation GetFoundationProc(TileIndex tile, Slope tileh);
 
 /**
- * Called when a tile is affected by a terraforming operation.
- * The function has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype.
- * With DC_EXEC in flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself).
+ * Tile callback function signature of the terraforming callback.
+ *
+ * The function is called when a tile is affected by a terraforming operation.
+ * It has to check if terraforming of the tile is allowed and return extra terraform-cost that depend on the tiletype.
+ * With DC_EXEC in \a flags it has to perform tiletype-specific actions (like clearing land etc., but not the terraforming itself).
  *
  * @note The terraforming has not yet taken place. So GetTileZ() and GetTileSlope() refer to the landscape before the terraforming operation.
  *
@@ -106,20 +133,20 @@ typedef CommandCost TerraformTileProc(TileIndex tile, uint32 flags, uint z_new,
  * Set of callback functions for performing tile operations of a given tile type.
  * @see TileType */
 struct TileTypeProcs {
-	DrawTileProc *draw_tile_proc;
+	DrawTileProc *draw_tile_proc;                  ///< Called to render the tile and its contents to the screen
 	GetSlopeZProc *get_slope_z_proc;
 	ClearTileProc *clear_tile_proc;
-	GetAcceptedCargoProc *get_accepted_cargo_proc;
-	GetTileDescProc *get_tile_desc_proc;
-	GetTileTrackStatusProc *get_tile_track_status_proc;
-	ClickTileProc *click_tile_proc;
+	GetAcceptedCargoProc *get_accepted_cargo_proc; ///< Return accepted cargo of the tile
+	GetTileDescProc *get_tile_desc_proc;           ///< Get a description of a tile (for the 'land area information' tool)
+	GetTileTrackStatusProc *get_tile_track_status_proc; ///< Get available tracks and status of a tile
+	ClickTileProc *click_tile_proc;                ///< Called when tile is clicked
 	AnimateTileProc *animate_tile_proc;
 	TileLoopProc *tile_loop_proc;
 	ChangeTileOwnerProc *change_tile_owner_proc;
-	GetProducedCargoProc *get_produced_cargo_proc;
-	VehicleEnterTileProc *vehicle_enter_tile_proc;
+	GetProducedCargoProc *get_produced_cargo_proc; ///< Return produced cargo of the tile
+	VehicleEnterTileProc *vehicle_enter_tile_proc; ///< Called when a vehicle enters a tile
 	GetFoundationProc *get_foundation_proc;
-	TerraformTileProc *terraform_tile_proc;
+	TerraformTileProc *terraform_tile_proc;        ///< Called when a terraforming operation is about to take place
 };
 
 extern const TileTypeProcs * const _tile_type_procs[16];
diff --git a/src/tile_map.cpp b/src/tile_map.cpp
index f6cb0adef..27b0a08a1 100644
--- a/src/tile_map.cpp
+++ b/src/tile_map.cpp
@@ -7,6 +7,11 @@
 #include "tile_map.h"
 #include "core/math_func.hpp"
 
+/**
+ * Return the slope of a given tile
+ * @param tile Tile to compute slope of
+ * @param h    If not \c NULL, pointer to storage of z height
+ * @return Slope of the tile, except for the HALFTILE part */
 Slope GetTileSlope(TileIndex tile, uint *h)
 {
 	uint a;
@@ -42,6 +47,10 @@ Slope GetTileSlope(TileIndex tile, uint *h)
 	return (Slope)r;
 }
 
+/**
+ * Get bottom height of the tile
+ * @param tile Tile to compute height of
+ * @return Minimum height of the tile */
 uint GetTileZ(TileIndex tile)
 {
 	if (TileX(tile) == MapMaxX() || TileY(tile) == MapMaxY()) return 0;
@@ -54,7 +63,10 @@ uint GetTileZ(TileIndex tile)
 	return h * TILE_HEIGHT;
 }
 
-
+/**
+ * Get top height of the tile
+ * @param tile Tile to compute height of
+ * @return Maximum height of the tile */
 uint GetTileMaxZ(TileIndex t)
 {
 	if (TileX(t) == MapMaxX() || TileY(t) == MapMaxY()) return 0;
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
index 11167bde0..4b3d19364 100644
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -224,6 +224,7 @@ static uint GetSlopeZ_Town(TileIndex tile, uint x, uint y)
 	return GetTileMaxZ(tile);
 }
 
+/** Tile callback routine */
 static Foundation GetFoundation_Town(TileIndex tile, Slope tileh)
 {
 	return FlatteningFoundation(tileh);
@@ -399,7 +400,7 @@ static void MakeSingleHouseBigger(TileIndex tile)
 	MarkTileDirtyByTile(tile);
 }
 
-/** Make the house advances in its construction stages until completion
+/** Make the house advance in its construction stages until completion
  * @param tile TileIndex of house
  */
 static void MakeTownHouseBigger(TileIndex tile)
@@ -412,6 +413,8 @@ static void MakeTownHouseBigger(TileIndex tile)
 }
 
 /**
+ * Tile callback function.
+ *
  * Periodic tic handler for houses and town
  * @param tile been asked to do its stuff
  */
@@ -507,7 +510,7 @@ static void TileLoop_Town(TileIndex tile)
 }
 
 /**
- * Unused handler
+ * Dummy tile callback function for handling tile clicks in towns
  * @param tile unused
  */
 static void ClickTile_Town(TileIndex tile)
@@ -2002,7 +2005,12 @@ static bool BuildTownHouse(Town *t, TileIndex tile)
 	return false;
 }
 
-
+/**
+ * Update data structures when a house is removed
+ * @param tile  Tile of the house
+ * @param t     Town owning the house
+ * @param house House type
+ */
 static void DoClearTownHouseHelper(TileIndex tile, Town *t, HouseID house)
 {
 	assert(IsTileType(tile, MP_HOUSE));
@@ -2601,6 +2609,7 @@ static CommandCost TerraformTile_Town(TileIndex tile, uint32 flags, uint z_new,
 	return DoCommand(tile, 0, 0, flags, CMD_LANDSCAPE_CLEAR);
 }
 
+/** Tile callback functions for a town */
 extern const TileTypeProcs _tile_type_town_procs = {
 	DrawTile_Town,           // draw_tile_proc
 	GetSlopeZ_Town,          // get_slope_z_proc
diff --git a/src/transport_type.h b/src/transport_type.h
index c23afbd7c..c31a0ae79 100644
--- a/src/transport_type.h
+++ b/src/transport_type.h
@@ -7,6 +7,7 @@
 
 typedef uint16 UnitID;
 
+/** Available types of transport */
 enum TransportType {
 	/* These constants are for now linked to the representation of bridges
 	 * and tunnels, so they can be used by GetTileTrackStatus_TunnelBridge.
@@ -15,10 +16,10 @@ enum TransportType {
 	 * the values for road and rail.
 	 */
 	TRANSPORT_BEGIN = 0,
-	TRANSPORT_RAIL = TRANSPORT_BEGIN,
-	TRANSPORT_ROAD,
-	TRANSPORT_WATER,
-	TRANSPORT_AIR,
+	TRANSPORT_RAIL = TRANSPORT_BEGIN, ///< Transport by train
+	TRANSPORT_ROAD,  ///< Transport by road vehicle
+	TRANSPORT_WATER, ///< Transport over water
+	TRANSPORT_AIR,   ///< Transport through air
 	TRANSPORT_END,
 	INVALID_TRANSPORT = 0xff,
 };
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index 0da7e16b6..1d1a5c4bf 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -1779,7 +1779,10 @@ void MarkSingleVehicleDirty(const Vehicle *v)
 	MarkAllViewportsDirty(v->left_coord, v->top_coord, v->right_coord + 1, v->bottom_coord + 1);
 }
 
-/* returns true if staying in the same tile */
+/**
+ * Get position information of a vehicle when moving one pixel in the direction it is facing
+ * @param v Vehicle to move
+ * @return Position information after the move */
 GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v)
 {
 	static const int8 _delta_coord[16] = {
@@ -1870,7 +1873,12 @@ Trackdir GetVehicleTrackdir(const Vehicle *v)
 }
 
 /**
- * Returns some meta-data over the to be entered tile.
+ * Call the tile callback function for a vehicle entering a tile
+ * @param v    Vehicle entering the tile
+ * @param tile Tile entered
+ * @param x    X position
+ * @param y    Y position
+ * @return Some meta-data over the to be entered tile.
  * @see VehicleEnterTileStatus to see what the bits in the return value mean.
  */
 uint32 VehicleEnterTile(Vehicle *v, TileIndex tile, int x, int y)
diff --git a/src/vehicle_func.h b/src/vehicle_func.h
index 6b0c36930..e17b0f39d 100644
--- a/src/vehicle_func.h
+++ b/src/vehicle_func.h
@@ -75,14 +75,13 @@ bool CanBuildVehicleInfrastructure(VehicleType type);
 
 void CcCloneVehicle(bool success, TileIndex tile, uint32 p1, uint32 p2);
 
-
+/** Position information of a vehicle after it moved */
 struct GetNewVehiclePosResult {
-	int x, y;
-	TileIndex old_tile;
-	TileIndex new_tile;
+	int x, y;  ///< x and y position of the vehicle after moving
+	TileIndex old_tile; ///< Current tile of the vehicle
+	TileIndex new_tile; ///< Tile of the vehicle after moving
 };
 
-/* returns true if staying in the same tile */
 GetNewVehiclePosResult GetNewVehiclePos(const Vehicle *v);
 Direction GetDirectionTowards(const Vehicle *v, int x, int y);