(svn r9664) -Documentation: Doxygen corrections,errors and omissions

9 files changed, 78 insertions, 14 deletions

diff --git a/src/os2.cpp b/src/os2.cpp
index 3ce2caf8d..9cdc7c43b 100644
--- a/src/os2.cpp
+++ b/src/os2.cpp
@@ -169,7 +169,7 @@ int CDECL main(int argc, char* argv[])
  * Insert a chunk of text from the clipboard onto the textbuffer. Get TEXT clipboard
  * and append this up to the maximum length (either absolute or screenlength). If maxlength
  * is zero, we don't care about the screenlength but only about the physical length of the string
- * @param tb @Textbuf type to be changed
+ * @param tb Textbuf type to be changed
  * @return Return true on successfull change of Textbuf, or false otherwise
  */
 bool InsertTextBufferClipboard(Textbuf *tb)
diff --git a/src/players.cpp b/src/players.cpp
index 32ec42725..eb4bd1712 100644
--- a/src/players.cpp
+++ b/src/players.cpp
@@ -622,6 +622,7 @@ static void DeletePlayerStuff(PlayerID pi)
 
 /** Change engine renewal parameters
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 bits 0-3 command
  * - p1 = 0 - change auto renew bool
  * - p1 = 1 - change auto renew months
@@ -755,6 +756,7 @@ int32 CmdSetAutoReplace(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Control the players: add, delete, etc.
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 various functionality
  * - p1 = 0 - create a new player, Which player (network) it will be is in p2
  * - p1 = 1 - create a new AI player
diff --git a/src/rail_cmd.cpp b/src/rail_cmd.cpp
index 15f80502e..af3ae13c2 100644
--- a/src/rail_cmd.cpp
+++ b/src/rail_cmd.cpp
@@ -230,6 +230,7 @@ static inline bool ValParamTrackOrientation(Track track) {return IsValidTrack(tr
 
 /** Build a single piece of rail
  * @param tile tile  to build on
+ * @param flags operation to perform
  * @param p1 railtype of being built piece (normal, mono, maglev)
  * @param p2 rail track to build
  */
@@ -332,6 +333,7 @@ int32 CmdBuildSingleRail(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Remove a single piece of track
  * @param tile tile to remove track from
+ * @param flags operation to perform
  * @param p1 unused
  * @param p2 rail orientation
  */
@@ -477,6 +479,7 @@ static int32 ValidateAutoDrag(Trackdir *trackdir, TileIndex start, TileIndex end
 
 /** Build a stretch of railroad tracks.
  * @param tile start tile of drag
+ * @param flags operation to perform
  * @param p1 end tile of drag
  * @param p2 various bitstuffed elements
  * - p2 = (bit 0-3) - railroad type normal/maglev (0 = normal, 1 = mono, 2 = maglev)
@@ -526,6 +529,13 @@ static int32 CmdRailTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint32
 
 /** Build rail on a stretch of track.
  * Stub for the unified rail builder/remover
+ * @param tile start tile of drag
+ * @param flags operation to perform
+ * @param p1 end tile of drag
+ * @param p2 various bitstuffed elements
+ * - p2 = (bit 0-3) - railroad type normal/maglev (0 = normal, 1 = mono, 2 = maglev)
+ * - p2 = (bit 4-6) - track-orientation, valid values: 0-5 (Track enum)
+ * - p2 = (bit 7)   - 0 = build, 1 = remove tracks
  * @see CmdRailTrackHelper
  */
 int32 CmdBuildRailroadTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
@@ -535,6 +545,13 @@ int32 CmdBuildRailroadTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Build rail on a stretch of track.
  * Stub for the unified rail builder/remover
+ * @param tile start tile of drag
+ * @param flags operation to perform
+ * @param p1 end tile of drag
+ * @param p2 various bitstuffed elements
+ * - p2 = (bit 0-3) - railroad type normal/maglev (0 = normal, 1 = mono, 2 = maglev)
+ * - p2 = (bit 4-6) - track-orientation, valid values: 0-5 (Track enum)
+ * - p2 = (bit 7)   - 0 = build, 1 = remove tracks
  * @see CmdRailTrackHelper
  */
 int32 CmdRemoveRailroadTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
@@ -544,6 +561,7 @@ int32 CmdRemoveRailroadTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Build a train depot
  * @param tile position of the train depot
+ * @param flags operation to perform
  * @param p1 rail type
  * @param p2 bit 0..1 entrance direction (DiagDirection)
  *
@@ -609,6 +627,7 @@ int32 CmdBuildTrainDepot(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
  * pre/exit/combo-signals, and what-else not. If the rail piece does not
  * have any signals, bit 4 (cycle signal-type) is ignored
  * @param tile tile where to build the signals
+ * @param flags operation to perform
  * @param p1 various bitstuffed elements
  * - p1 = (bit 0-2) - track-orientation, valid values: 0-5 (Track enum)
  * - p1 = (bit 3)   - 1 = override signal/semaphore, or pre/exit/combo signal (CTRL-toggle)
@@ -703,6 +722,7 @@ int32 CmdBuildSingleSignal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Build many signals by dragging; AutoSignals
  * @param tile start tile of drag
+ * @param flags operation to perform
  * @param p1  end tile of drag
  * @param p2 various bitstuffed elements
  * - p2 = (bit  0- 2) - track-orientation, valid values: 0-5 (Track enum)
@@ -790,6 +810,15 @@ static int32 CmdSignalTrackHelper(TileIndex tile, uint32 flags, uint32 p1, uint3
 
 /** Build signals on a stretch of track.
  * Stub for the unified signal builder/remover
+ * @param tile start tile of drag
+ * @param flags operation to perform
+ * @param p1  end tile of drag
+ * @param p2 various bitstuffed elements
+ * - p2 = (bit  0- 2) - track-orientation, valid values: 0-5 (Track enum)
+ * - p2 = (bit  3)    - 1 = override signal/semaphore, or pre/exit/combo signal (CTRL-toggle)
+ * - p2 = (bit  4)    - 0 = signals, 1 = semaphores
+ * - p2 = (bit  5)    - 0 = build, 1 = remove signals
+ * - p2 = (bit 24-31) - user defined signals_density
  * @see CmdSignalTrackHelper
  */
 int32 CmdBuildSignalTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
@@ -799,6 +828,7 @@ int32 CmdBuildSignalTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Remove signals
  * @param tile coordinates where signal is being deleted from
+ * @param flags operation to perform
  * @param various bitstuffed elements, only track information is used
  * - p1 = (bit  0- 2) - track-orientation, valid values: 0-5 (Track enum)
  * - p1 = (bit  3)    - override signal/semaphore, or pre/exit/combo signal (CTRL-toggle)
@@ -842,6 +872,15 @@ int32 CmdRemoveSingleSignal(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Remove signals on a stretch of track.
  * Stub for the unified signal builder/remover
+ * @param tile start tile of drag
+ * @param flags operation to perform
+ * @param p1  end tile of drag
+ * @param p2 various bitstuffed elements
+ * - p2 = (bit  0- 2) - track-orientation, valid values: 0-5 (Track enum)
+ * - p2 = (bit  3)    - 1 = override signal/semaphore, or pre/exit/combo signal (CTRL-toggle)
+ * - p2 = (bit  4)    - 0 = signals, 1 = semaphores
+ * - p2 = (bit  5)    - 0 = build, 1 = remove signals
+ * - p2 = (bit 24-31) - user defined signals_density
  * @see CmdSignalTrackHelper
  */
 int32 CmdRemoveSignalTrack(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
@@ -908,6 +947,7 @@ extern int32 DoConvertTunnelBridgeRail(TileIndex tile, RailType totype, bool exe
 /** Convert one rail type to the other. You can convert normal rail to
  * monorail/maglev easily or vice-versa.
  * @param tile end tile of rail conversion drag
+ * @param flags operation to perform
  * @param p1 start tile of drag
  * @param p2 new railtype to convert to
  */
@@ -1177,9 +1217,6 @@ static void DrawTrackDetails(const TileInfo* ti)
  * Draw ground sprite and track bits
  * @param ti TileInfo
  * @param track TrackBits to draw
- * @param earth Draw as earth
- * @param snow Draw as snow
- * @param flat Always draw foundation
  */
 static void DrawTrackBits(TileInfo* ti, TrackBits track)
 {
diff --git a/src/road_cmd.cpp b/src/road_cmd.cpp
index 0ec31702f..5f98ae9d5 100644
--- a/src/road_cmd.cpp
+++ b/src/road_cmd.cpp
@@ -90,6 +90,7 @@ static bool CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, bool *edge_roa
 
 /** Delete a piece of road.
  * @param tile tile where to remove road from
+ * @param flags operation to perform
  * @param p1 bit 0..3 road pieces to remove (RoadBits)
  * @param p2 unused
  */
@@ -251,6 +252,7 @@ static uint32 CheckRoadSlope(Slope tileh, RoadBits* pieces, RoadBits existing)
 
 /** Build a piece of road.
  * @param tile tile where to build road
+ * @param flags operation to perform
  * @param p1 bit 0..3 road pieces to build (RoadBits)
  * @param p2 the town that is building the road (0 if not applicable)
  */
@@ -402,6 +404,7 @@ int32 DoConvertStreetRail(TileIndex tile, RailType totype, bool exec)
 
 /** Build a long piece of road.
  * @param end_tile end tile of drag
+ * @param flags operation to perform
  * @param p1 start tile of drag
  * @param p2 various bitstuffed elements
  * - p2 = (bit 0) - start tile starts in the 2nd half of tile (p2 & 1)
@@ -458,6 +461,7 @@ int32 CmdBuildLongRoad(TileIndex end_tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Remove a long piece of road.
  * @param end_tile end tile of drag
+ * @param flags operation to perform
  * @param p1 start tile of drag
  * @param p2 various bitstuffed elements
  * - p2 = (bit 0) - start tile starts in the 2nd half of tile (p2 & 1)
@@ -512,6 +516,7 @@ int32 CmdRemoveLongRoad(TileIndex end_tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Build a road depot.
  * @param tile tile where to build the depot
+ * @param flags operation to perform
  * @param p1 bit 0..1 entrance direction (DiagDirection)
  * @param p2 unused
  *
@@ -659,7 +664,6 @@ const byte _road_sloped_sprites[14] = {
 /**
  * Draw ground sprite and road pieces
  * @param ti TileInfo
- * @param road RoadBits to draw
  */
 static void DrawRoadBits(TileInfo* ti)
 {
diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp
index 7cf2c8eeb..cef00e34e 100644
--- a/src/roadveh_cmd.cpp
+++ b/src/roadveh_cmd.cpp
@@ -122,6 +122,7 @@ static int32 EstimateRoadVehCost(EngineID engine_type)
 
 /** Build a road vehicle.
  * @param tile tile of depot where road vehicle is built
+ * @param flags operation to perform
  * @param p1 bus/truck type being built (engine)
  * @param p2 bit 0 when set, the unitnumber will be 0, otherwise it will be a free number
  */
@@ -227,6 +228,7 @@ int32 CmdBuildRoadVeh(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Start/Stop a road vehicle.
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 road vehicle ID to start/stop
  * @param p2 unused
  */
@@ -278,6 +280,7 @@ void ClearSlot(Vehicle *v)
 
 /** Sell a road vehicle.
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 vehicle ID to be sold
  * @param p2 unused
  */
@@ -375,6 +378,7 @@ static const Depot* FindClosestRoadDepot(const Vehicle* v)
 
 /** Send a road vehicle to the depot.
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 vehicle ID to send to the depot
  * @param p2 various bitmasked elements
  * - p2 bit 0-3 - DEPOT_ flags (see vehicle.h)
@@ -447,6 +451,7 @@ int32 CmdSendRoadVehToDepot(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
 
 /** Turn a roadvehicle around.
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 vehicle ID to turn
  * @param p2 unused
  */
@@ -1066,10 +1071,10 @@ static inline NPFFoundTargetData PerfNPFRouteToStationOrTile(TileIndex tile, Tra
 /**
  * Returns direction to for a road vehicle to take or
  * INVALID_TRACKDIR if the direction is currently blocked
- * @param v        the vehicle to do the pathfinding for
+ * @param v        the Vehicle to do the pathfinding for
  * @param tile     the where to start the pathfinding
  * @param enterdir the direction the vehicle enters the tile from
- * @return the trackdir to take
+ * @return the Trackdir to take
  */
 static Trackdir RoadFindPathToDest(Vehicle* v, TileIndex tile, DiagDirection enterdir)
 {
@@ -1841,6 +1846,7 @@ void RoadVehiclesYearlyLoop()
 
 /** Refit a road vehicle to the specified cargo type
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 Vehicle ID of the vehicle to refit
  * @param p2 Bitstuffed elements
  * - p2 = (bit 0-7) - the new cargo type to refit to
diff --git a/src/settings.cpp b/src/settings.cpp
index 1adc2b9a3..bdf488823 100644
--- a/src/settings.cpp
+++ b/src/settings.cpp
@@ -412,7 +412,7 @@ static int lookup_oneofmany(const char *many, const char *one, int onelen)
 /** Find the set-integer value MANYofMANY type in a string
  * @param many full domain of values the MANYofMANY setting can have
  * @param str the current string value of the setting, each individual
- * of seperated by a whitespace\tab or | character
+ * of seperated by a whitespace,tab or | character
  * @return the 'fully' set integer, or -1 if a set is not found */
 static uint32 lookup_manyofmany(const char *many, const char *str)
 {
@@ -682,7 +682,8 @@ static void Write_ValidateSetting(void *ptr, const SettingDesc *sd, int32 val)
  * @param ini pointer to IniFile structure that holds administrative information
  * @param sd pointer to SettingDesc structure whose internally pointed variables will
  *        be given values
- * @param grpname the group of the IniFile to search in for the new values */
+ * @param grpname the group of the IniFile to search in for the new values
+ * @param object pointer to the object been loaded */
 static void ini_load_settings(IniFile *ini, const SettingDesc *sd, const char *grpname, void *object)
 {
 	IniGroup *group;
@@ -752,6 +753,7 @@ static void ini_load_settings(IniFile *ini, const SettingDesc *sd, const char *g
  * @param sd read-only SettingDesc structure which contains the unmodified,
  *        loaded values of the configuration file and various information about it
  * @param grpname holds the name of the group (eg. [network]) where these will be saved
+ * @param object pointer to the object been saved
  * The function works as follows: for each item in the SettingDesc structure we
  * have a look if the value has changed since we started the game (the original
  * values are reloaded when saving). If settings indeed have changed, we get
@@ -865,7 +867,7 @@ static void ini_save_settings(IniFile *ini, const SettingDesc *sd, const char *g
  * The list parameter can be a NULL pointer, in this case nothing will be
  * saved and a callback function should be defined that will take over the
  * list-handling and store the data itself somewhere.
- * @param IniFile handle to the ini file with the source data
+ * @param ini IniFile handle to the ini file with the source data
  * @param grpname character string identifying the section-header of the ini
  * file that will be parsed
  * @param list pointer to an string(pointer) array that will store the parsed
@@ -1728,6 +1730,8 @@ static const SettingDesc *GetSettingDescription(uint index)
 }
 
 /** Network-safe changing of patch-settings (server-only).
+ * @param tile unused
+ * @param flags operation to perform
  * @param p1 the index of the patch in the SettingDesc array which identifies it
  * @param p2 the new value for the patch
  * The new value is properly clamped to its minimum/maximum when setting
@@ -1878,6 +1882,7 @@ static void LoadSettings(const SettingDesc *osd, void *object)
 }
 
 /** Loadhandler for a list of global variables
+ * @param sdg pointer for the global variable list SettingDescGlobVarList
  * @note this is actually a stub for LoadSettings with the
  * object pointer set to NULL */
 static inline void LoadSettingsGlobList(const SettingDescGlobVarList *sdg)
@@ -1886,7 +1891,7 @@ static inline void LoadSettingsGlobList(const SettingDescGlobVarList *sdg)
 }
 
 /** Save and load handler for patches/settings
- * @param osd SettingDesc struct containing all information
+ * @param sd SettingDesc struct containing all information
  * @param object can be either NULL in which case we load global variables or
  * a pointer to a struct which is getting saved */
 static void SaveSettings(const SettingDesc *sd, void *object)
diff --git a/src/settings_gui.cpp b/src/settings_gui.cpp
index 90f2b87a3..c1497b814 100644
--- a/src/settings_gui.cpp
+++ b/src/settings_gui.cpp
@@ -225,6 +225,7 @@ static void GameOptionsWndProc(Window *w, WindowEvent *e)
 
 /** Change the side of the road vehicles drive on (server only).
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 the side of the road; 0 = left side and 1 = right side
  * @param p2 unused
  */
diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp
index 814c1066a..bee2ae9d1 100644
--- a/src/smallmap_gui.cpp
+++ b/src/smallmap_gui.cpp
@@ -396,7 +396,7 @@ static inline uint32 GetSmallMapContoursPixels(TileIndex tile)
 /**
  * Return the color a tile would be displayed with in the small map in mode "Vehicles".
  *
- * @param t The tile of which we would like to get the color.
+ * @param tile The tile of which we would like to get the color.
  * @return The color of tile in the small map in mode "Vehicles"
  */
 static inline uint32 GetSmallMapVehiclesPixels(TileIndex tile)
@@ -426,7 +426,7 @@ static inline uint32 GetSmallMapIndustriesPixels(TileIndex tile)
 /**
  * Return the color a tile would be displayed with in the small map in mode "Routes".
  *
- * @param t The tile of which we would like to get the color.
+ * @param tile The tile of which we would like to get the color.
  * @return The color of tile  in the small map in mode "Routes"
  */
 static inline uint32 GetSmallMapRoutesPixels(TileIndex tile)
@@ -502,7 +502,7 @@ static uint32 _owner_colors[OWNER_END + 1];
 /**
  * Return the color a tile would be displayed with in the small map in mode "Owner".
  *
- * @param t The tile of which we would like to get the color.
+ * @param tile The tile of which we would like to get the color.
  * @return The color of tile in the small map in mode "Owner"
  */
 static inline uint32 GetSmallMapOwnerPixels(TileIndex tile)
diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp
index eaf0db70d..5c526fb49 100644
--- a/src/station_cmd.cpp
+++ b/src/station_cmd.cpp
@@ -789,6 +789,7 @@ static void GetStationLayout(byte *layout, int numtracks, int plat_len, const St
 
 /** Build railroad station
  * @param tile_org starting position of station dragging/placement
+ * @param flags operation to perform
  * @param p1 various bitstuffed elements
  * - p1 = (bit  0)    - orientation (Axis)
  * - p1 = (bit  8-15) - number of tracks
@@ -1023,6 +1024,7 @@ restart:
 /** Remove a single tile from a railroad station.
  * This allows for custom-built station with holes and weird layouts
  * @param tile tile of station piece to remove
+ * @param flags operation to perform
  * @param p1 unused
  * @param p2 unused
  */
@@ -1174,6 +1176,8 @@ 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
@@ -1341,6 +1345,7 @@ static int32 RemoveRoadStop(Station *st, uint32 flags, TileIndex tile)
 
 /** Remove a bus or truck stop
  * @param tile tile to remove the stop from
+ * @param flags operation to perform
  * @param p1 not used
  * @param p2 bit 0: 0 for Bus stops, 1 for truck stops
  */
@@ -1466,6 +1471,7 @@ static const byte * const _airport_sections[] = {
 
 /** Place an Airport.
  * @param tile tile where airport will be built
+ * @param flags operation to perform
  * @param p1 airport type, @see airport.h
  * @param p2 unused
  */
@@ -1641,6 +1647,7 @@ static int32 RemoveAirport(Station *st, uint32 flags)
 
 /** Build a buoy.
  * @param tile tile where to place the bouy
+ * @param flags operation to perform
  * @param p1 unused
  * @param p2 unused
  */
@@ -1749,6 +1756,7 @@ static const byte _dock_h_chk[4] = { 1, 2, 1, 2 };
 
 /** Build a dock/haven.
  * @param tile tile where dock will be built
+ * @param flags operation to perform
  * @param p1 unused
  * @param p2 unused
  */
@@ -2381,6 +2389,7 @@ static void UpdateStationWaiting(Station *st, CargoID type, uint amount)
 
 /** Rename a station
  * @param tile unused
+ * @param flags operation to perform
  * @param p1 station ID that is to be renamed
  * @param p2 unused
  */