(svn r9665) -Documentation: Doxygen corrections,errors, corrections of corrections...

11 files changed, 32 insertions, 26 deletions

diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
index 5c526fb49..4dd10ed98 100644
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -1177,7 +1177,6 @@ static RoadStop **FindRoadStopSpot(bool truck_station, Station* st)
 /** Build a bus or truck stop
  * @param tile tile to build the stop at
  * @param flags operation to perform
- * @param flags operation to perform
  * @param p1 entrance direction (DiagDirection)
  * @param p2 bit 0: 0 for Bus stops, 1 for truck stops
  *           bit 1: 0 for normal, 1 for drive-through
diff --git a/src/table/sprites.h b/src/table/sprites.h
index 0301d9f20..da80b4954 100644
--- a/src/table/sprites.h
+++ b/src/table/sprites.h
@@ -1302,7 +1302,7 @@ enum AnimCursors {
  * <li> TRANSPARENT_BIT is the bit number which toggles sprite transparency</li>
  * <li> RECOLOR_BIT toggles the recoloring system</li>
  * <li> PALETTE_SPRITE_WIDTH and PALETTE_SPRITE_START determine the position and number of
- * bits used for the recoloring process. For transparency, it must be 0x322.</li>
+ * bits used for the recoloring process. For transparency, it must be 0x322.</li></ul>
  */
 enum SpriteSetup {
 	TRANSPARENT_BIT = 31,       ///< toggles transparency in the sprite
diff --git a/src/town.h b/src/town.h
index 75157bde3..c181f1b25 100644
--- a/src/town.h
+++ b/src/town.h
@@ -279,7 +279,7 @@ static inline bool IsValidTown(const Town* town)
 
 /**
  * Check if a TownID is valid.
- * @param TownID to inquiry
+ * @param index to inquiry in the pool of town
  * @return true if it exists
  */
 static inline bool IsValidTownID(TownID index)
diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp
index 31e76fb83..f83f7dcb8 100644
--- a/src/town_cmd.cpp
+++ b/src/town_cmd.cpp
@@ -1543,6 +1543,7 @@ static bool DoBuildStatueOfCompany(TileIndex tile, TownID town_id)
 
 /**
  * Search callback function for TownActionBuildStatue
+ * @param tile on which to perform the search
  * @param town_id The town_id for which we want a statue
  * @return the result of the test
  */
diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp
index 51f0f1ecf..4855ef8e0 100644
--- a/src/train_cmd.cpp
+++ b/src/train_cmd.cpp
@@ -3107,7 +3107,7 @@ extern TileIndex CheckTunnelBusy(TileIndex tile, uint *length);
  * train, then goes to the last wagon and deletes that. Each call to this function
  * will remove the last wagon of a crashed train. If this wagon was on a crossing,
  * or inside a tunnel, recalculate the signals as they might need updating
- * @param v the @Vehicle of which last wagon is to be removed
+ * @param v the Vehicle of which last wagon is to be removed
  */
 static void DeleteLastWagon(Vehicle *v)
 {
diff --git a/src/tunnelbridge_cmd.cpp b/src/tunnelbridge_cmd.cpp
index e7a4b5718..f6131f5a1 100644
--- a/src/tunnelbridge_cmd.cpp
+++ b/src/tunnelbridge_cmd.cpp
@@ -440,7 +440,7 @@ not_valid_below:;
 
 
 /** Build Tunnel.
- * @param tile start tile of tunnel
+ * @param start_tile start tile of tunnel
  * @param flags type of operation
  * @param p1 railtype, 0x200 for road tunnel
  * @param p2 unused
diff --git a/src/unmovable_cmd.cpp b/src/unmovable_cmd.cpp
index 4e496ec21..4fc3b7b96 100644
--- a/src/unmovable_cmd.cpp
+++ b/src/unmovable_cmd.cpp
@@ -27,8 +27,9 @@
 /** Destroy a HQ.
  * During normal gameplay you can only implicitely destroy a HQ when you are
  * rebuilding it. Otherwise, only water can destroy it.
- * @param tile tile coordinates where HQ is located to destroy
+ * @param pid Player requesting the destruction of his HQ
  * @param flags docommand flags of calling function
+ * @return cost of the operation
  */
 static int32 DestroyCompanyHQ(PlayerID pid, uint32 flags)
 {
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index 4e74afed2..e6ccce323 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -767,7 +767,7 @@ bool CanRefitTo(EngineID engine_type, CargoID cid_to)
 }
 
 /** Find the first cargo type that an engine can be refitted to.
- * @param engine Which engine to find cargo for.
+ * @param engine_type Which engine to find cargo for.
  * @return A climate dependent cargo type. CT_INVALID is returned if not refittable.
  */
 CargoID FindFirstRefittableCargo(EngineID engine_type)
@@ -784,7 +784,7 @@ CargoID FindFirstRefittableCargo(EngineID engine_type)
 }
 
 /** Learn the price of refitting a certain engine
-* @param engine Which engine to refit
+* @param engine_type Which engine to refit
 * @return Price for refitting
 */
 int32 GetRefitCost(EngineID engine_type)
@@ -1904,7 +1904,7 @@ static inline void ExtendVehicleListSize(const Vehicle ***engine_list, uint16 *e
 /** Generates a list of vehicles inside a depot
  * Will enlarge allocated space for the list if they are too small, so it's ok to call with (pointer to NULL array, pointer to uninitised uint16, pointer to 0)
  * If one of the lists is not needed (say wagons when finding ships), all the pointers regarding that list should be set to NULL
- * @param Type type of vehicle
+ * @param type Type of vehicle
  * @param tile The tile the depot is located in
  * @param ***engine_list Pointer to a pointer to an array of vehicles in the depot (old list is freed and a new one is malloced)
  * @param *engine_list_length Allocated size of engine_list. Needs to be set to 0 when engine_list points to a NULL array
@@ -1986,11 +1986,13 @@ void BuildDepotVehicleList(byte type, TileIndex tile, Vehicle ***engine_list, ui
 * @param length_of_array informs the length allocated for sort_list. This is not the same as the number of vehicles in the list. Needs to be 0 when sort_list is NULL
 * @param type type of vehicle
 * @param owner PlayerID of owner to generate a list for
-* @param index This parameter got different meanings depending on window_type
-			VLW_STATION_LIST:  index of station to generate a list for
-			VLW_SHARED_ORDERS: index of order to generate a list for
-			VLW_STANDARD: not used
-			VLW_DEPOT_LIST: TileIndex of the depot/hangar to make the list for
+* @param index This parameter has different meanings depending on window_type
+    <ul>
+      <li>VLW_STATION_LIST:  index of station to generate a list for</li>
+      <li>VLW_SHARED_ORDERS: index of order to generate a list for<li>
+      <li>VLW_STANDARD: not used<li>
+      <li>VLW_DEPOT_LIST: TileIndex of the depot/hangar to make the list for</li>
+    </ul>
 * @param window_type tells what kind of window the list is for. Use the VLW flags in vehicle_gui.h
 * @return the number of vehicles added to the list
 */
@@ -2088,7 +2090,7 @@ uint GenerateVehicleSortList(const Vehicle ***sort_list, uint16 *length_of_array
  * @param flags the flags used for DoCommand()
  * @param service should the vehicles only get service in the depots
  * @param owner PlayerID of owner of the vehicles to send
- * @param VLW_flag tells what kind of list requested the goto depot
+ * @param vlw_flag tells what kind of list requested the goto depot
  * @return 0 for success and CMD_ERROR if no vehicle is able to go to depot
  */
 int32 SendAllVehiclesToDepot(byte type, uint32 flags, bool service, PlayerID owner, uint16 vlw_flag, uint32 id)
diff --git a/src/vehicle_gui.cpp b/src/vehicle_gui.cpp
index d04f6fca0..03598d927 100644
--- a/src/vehicle_gui.cpp
+++ b/src/vehicle_gui.cpp
@@ -279,8 +279,11 @@ static RefitList *BuildRefitList(const Vehicle *v)
 
 /** Draw the list of available refit options for a consist.
  * Draw the list and highlight the selected refit option (if any)
- * @param *v first vehicle in consist to get the refit-options of
+ * @param *list first vehicle in consist to get the refit-options of
  * @param sel selected refit cargo-type in the window
+ * @param pos position of the selected item in caller widow
+ * @param rows number of rows(capacity) in caller window
+ * @param delta step height in caller window
  * @return the refit option that is hightlighted, NULL if none
  */
 static RefitOption *DrawVehicleRefitWindow(const RefitList *list, int sel, uint pos, uint rows, uint delta)
diff --git a/src/viewport.cpp b/src/viewport.cpp
index 2be6ec1d1..f536d09e8 100644
--- a/src/viewport.cpp
+++ b/src/viewport.cpp
@@ -2023,8 +2023,9 @@ static byte Check2x1AutoRail(int mode)
  * north-south (DIR_S) to obtain the same results with less code. This is what
  * the return value signifies.
  * @param style HighLightStyle dragging style
- * @param start_tile, end_tile start and end tile of drag
- * @param boolean value which when true means start/end should be swapped */
+ * @param start_tile start tile of drag
+ * @param end_tile end tile of drag
+ * @return boolean value which when true means start/end should be swapped */
 static bool SwapDirection(HighLightStyle style, TileIndex start_tile, TileIndex end_tile)
 {
 	uint start_x = TileX(start_tile);
diff --git a/src/yapf/yapf.h b/src/yapf/yapf.h
index cafd5df7e..1c2e08b33 100644
--- a/src/yapf/yapf.h
+++ b/src/yapf/yapf.h
@@ -20,7 +20,6 @@ Trackdir YapfChooseShipTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir,
  * @param v        the RV that needs to find a path
  * @param tile     the tile to find the path from (should be next tile the RV is about to enter)
  * @param enterdir diagonal direction which the RV will enter this new tile from
- * @param tracks   available tracks on the new tile (to choose from)
  * @return         the best trackdir for next turn or INVALID_TRACKDIR if the path could not be found
  */
 Trackdir YapfChooseRoadTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir);
@@ -29,8 +28,8 @@ Trackdir YapfChooseRoadTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir)
  * @param v        the train that needs to find a path
  * @param tile     the tile to find the path from (should be next tile the train is about to enter)
  * @param enterdir diagonal direction which the RV will enter this new tile from
- * @param trackdirs available trackdirs on the new tile (to choose from)
- * @param no_path_found [out] true is returned if no path can be found (returned Trackdir is only a 'guess')
+ * @param tracks   available trackdirs on the new tile (to choose from)
+ * @param path_not_found [out] true is returned if no path can be found (returned Trackdir is only a 'guess')
  * @return         the best trackdir for next turn or INVALID_TRACKDIR if the path could not be found
  */
 Trackdir YapfChooseRailTrack(Vehicle *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks, bool *path_not_found);
@@ -48,13 +47,13 @@ uint YapfRoadVehDistanceToTile(const Vehicle* v, TileIndex tile);
 Depot* YapfFindNearestRoadDepot(const Vehicle *v);
 
 /** Used when user sends train to the nearest depot or if train needs servicing.
- * @v            train that needs to go to some depot
- * @max_distance max distance (number of track tiles) from the current train position
+ * @param v            train that needs to go to some depot
+ * @param max_distance max distance (number of track tiles) from the current train position
  *                  (used also as optimization - the pathfinder can stop path finding if max_distance
  *                  was reached and no depot was seen)
- * @reverse_penalty penalty that should be added for the path that requires reversing the train first
- * @depot_tile   receives the depot tile if depot was found
- * @reversed     receives true if train needs to reversed first
+ * @param reverse_penalty penalty that should be added for the path that requires reversing the train first
+ * @param depot_tile   receives the depot tile if depot was found
+ * @param reversed     receives true if train needs to reversed first
  * @return       the true if depot was found.
  */
 bool YapfFindNearestRailDepotTwoWay(Vehicle *v, int max_distance, int reverse_penalty, TileIndex* depot_tile, bool* reversed);