(svn r17570) -Fix: a number of Doxygen warnings about missing parameters, which were sometimes missing and sometimes just typos

src/ai/ai_instance.hpp

@@ -164,6 +164,7 @@ private:
 
 	/**
 	 * Save one object (int / string / arrray / table) to the savegame.
+	 * @param vm The virtual machine to get all the data from.
 	 * @param index The index on the squirrel stack of the element to save.
 	 * @param max_depth The maximum depth recursive arrays / tables will be stored
 	 *   with before an error is returned.

src/ai/api/ai_road.cpp

@@ -402,6 +402,7 @@ static bool NormaliseTileOffset(int32 *tile)
 /**
  * Check whether one can reach (possibly by building) a road piece the center
  * of the neighbouring tile. This includes roads and (drive through) stations.
+ * @param rts The road type we want to know reachability for
  * @param start_tile The tile to "enter" the neighbouring tile.
  * @param neighbour The direction to the neighbouring tile to "enter".
  * @return true if and only if the tile is reachable.

src/autoreplace_cmd.cpp

@@ -299,6 +299,7 @@ static inline CommandCost StartStopVehicle(const Vehicle *v, bool evaluate_callb
 /** Issue a train vehicle move command
  * @param v The vehicle to move
  * @param after The vehicle to insert 'v' after, or NULL to start new chain
+ * @param flags the command flags to use
  * @param whole_chain move all vehicles following 'v' (true), or only 'v' (false)
  * @return success or error
  */

src/autoreplace_func.h

@@ -24,8 +24,9 @@ void RemoveAllEngineReplacement(EngineRenewList *erl);
 
 /**
  * Retrieve the engine replacement in a given renewlist for an original engine type.
- * @param  erl The renewlist to search in.
+ * @param erl The renewlist to search in.
- * @param  engine Engine type to be replaced.
+ * @param engine Engine type to be replaced.
+ * @param group The group related to this replacement.
  * @return The engine type to replace with, or INVALID_ENGINE if no
  * replacement is in the list.
  */
@@ -36,6 +37,7 @@ EngineID EngineReplacement(EngineRenewList erl, EngineID engine, GroupID group);
  * @param erl The renewlist to add to.
  * @param old_engine The original engine type.
  * @param new_engine The replacement engine type.
+ * @param group The group related to this replacement.
  * @param flags The calling command flags.
  * @return 0 on success, CMD_ERROR on failure.
  */
@@ -45,6 +47,7 @@ CommandCost AddEngineReplacement(EngineRenewList *erl, EngineID old_engine, Engi
  * Remove an engine replacement from a given renewlist.
  * @param erl The renewlist from which to remove the replacement
  * @param engine The original engine type.
+ * @param group The group related to this replacement.
  * @param flags The calling command flags.
  * @return 0 on success, CMD_ERROR on failure.
  */
@@ -63,6 +66,7 @@ static inline void RemoveAllEngineReplacementForCompany(Company *c)
  * Retrieve the engine replacement for the given company and original engine type.
  * @param c company.
  * @param engine Engine type.
+ * @param group The group related to this replacement.
  * @return The engine type to replace with, or INVALID_ENGINE if no
  * replacement is in the list.
  */
@@ -74,7 +78,8 @@ static inline EngineID EngineReplacementForCompany(const Company *c, EngineID en
 /**
  * Check if a company has a replacement set up for the given engine.
  * @param c Company.
- * @param  engine Engine type to be replaced.
+ * @param engine Engine type to be replaced.
+ * @param group The group related to this replacement.
  * @return true if a replacement was set up, false otherwise.
  */
 static inline bool EngineHasReplacementForCompany(const Company *c, EngineID engine, GroupID group)
@@ -87,6 +92,7 @@ static inline bool EngineHasReplacementForCompany(const Company *c, EngineID eng
  * @param c Company.
  * @param old_engine The original engine type.
  * @param new_engine The replacement engine type.
+ * @param group The group related to this replacement.
  * @param flags The calling command flags.
  * @return 0 on success, CMD_ERROR on failure.
  */
@@ -99,6 +105,7 @@ static inline CommandCost AddEngineReplacementForCompany(Company *c, EngineID ol
  * Remove an engine replacement for the company.
  * @param c Company.
  * @param engine The original engine type.
+ * @param group The group related to this replacement.
  * @param flags The calling command flags.
  * @return 0 on success, CMD_ERROR on failure.
  */

src/blitter/base.hpp

@@ -107,7 +107,8 @@ public:
 	/**
 	 * Make a single horizontal line in a single colour on the video-buffer.
 	 * @param video The destination pointer (video-buffer).
-	 * @param width The lenght of the line.
+	 * @param width The length of the line.
+	 * @param height The height of the line.
 	 * @param colour A 8bpp mapping colour.
 	 */
 	virtual void DrawRect(void *video, int width, int height, uint8 colour) = 0;

src/bridge_gui.cpp

@@ -45,7 +45,7 @@ typedef GUIList<BuildBridgeData> GUIBridgeList;
 /**
  * Callback executed after a build Bridge CMD has been called
  *
- * @param scucess True if the build succeded
+ * @param success True if the build succeded
  * @param tile The tile where the command has been executed
  * @param p1 not used
  * @param p2 not used
@@ -351,7 +351,7 @@ static const WindowDesc _build_bridge_desc(
  *  If we can't build a bridge under the given conditions
  *  show an error message.
  *
- * @parma start The start tile of the bridge
+ * @param start The start tile of the bridge
  * @param end The end tile of the bridge
  * @param transport_type The transport type
  * @param road_rail_type The road/rail type

src/build_vehicle_gui.cpp

@@ -701,12 +701,15 @@ int DrawVehiclePurchaseInfo(int left, int right, int y, EngineID engine_number)
 
 /** Engine drawing loop
  * @param type Type of vehicle (VEH_*)
- * @param x,y Where should the list start
+ * @param x The left most location of the list
+ * @param r The right most location of the list
+ * @param y The top most location of teh list
  * @param eng_list What engines to draw
  * @param min where to start in the list
  * @param max where in the list to end
  * @param selected_id what engine to highlight as selected, if any
  * @param count_location Offset to print the engine count (used by autoreplace). 0 means it's off
+ * @param selected_group the group to list the engines of
  */
 void DrawEngineList(VehicleType type, int x, int r, int y, const GUIEngineList *eng_list, uint16 min, uint16 max, EngineID selected_id, int count_location, GroupID selected_group)
 {

src/cargopacket.h

@@ -45,6 +45,8 @@ struct CargoPacket : CargoPacketPool::PoolItem<&_cargopacket_pool> {
 	 * Creates a new cargo packet
 	 * @param source the source of the packet
 	 * @param count  the number of cargo entities to put in this packet
+	 * @param source_type the 'type' of source the packet comes from (for subsidies)
+	 * @param source_id the actual source of the packet (for subsidies)
 	 * @pre count != 0 || source == INVALID_STATION
 	 */
 	CargoPacket(StationID source = INVALID_STATION, uint16 count = 0, SourceType source_type = ST_INDUSTRY, SourceID source_id = INVALID_SOURCE);

src/company_gui.cpp

@@ -1481,6 +1481,7 @@ static const NWidgetPart _nested_company_widgets[] = {
 /**
  * Draws text "Vehicles:" and number of all vehicle types, or "(none)"
  * @param company ID of company to print statistics of
+ * @param right the right most location to draw to
  */
 static void DrawCompanyVehiclesAmount(CompanyID company, int right)
 {

src/console_gui.cpp

@@ -465,7 +465,7 @@ static void IConsoleHistoryNavigate(int direction)
  * are also logged. All lines to print are added to a temporary buffer which can be
  * used as a history to print them onscreen
  * @param colour_code the colour of the command. Red in case of errors, etc.
- * @param string the message entered or output on the console (notice, error, etc.)
+ * @param str the message entered or output on the console (notice, error, etc.)
  */
 void IConsoleGUIPrint(ConsoleColour colour_code, char *str)
 {

src/core/math_func.hpp

@@ -245,7 +245,7 @@ static FORCEINLINE bool IsInsideBS(const T x, const uint base, const uint size)
  *
  * Returns true if a value is in the interval of [min, max).
  *
- * @param a The value to check
+ * @param x The value to check
  * @param min The minimum of the interval
  * @param max The maximum of the interval
  * @see IsInsideBS()

src/crashlog.h

@@ -44,7 +44,7 @@ protected:
 	 * Writes actually encountered error to the buffer.
 	 * @param buffer  The begin where to write at.
 	 * @param last    The last position in the buffer to write to.
-	 * @param messege Message passed to use for possible errors. Can be NULL.
+	 * @param message Message passed to use for possible errors. Can be NULL.
 	 * @return the position of the \c '\0' character after the buffer.
 	 */
 	virtual char *LogError(char *buffer, const char *last, const char *message) const = 0;

src/driver.cpp

@@ -61,6 +61,7 @@ int GetDriverParamInt(const char * const *parm, const char *name, int def)
 /**
  * Find the requested driver and return its class.
  * @param name the driver to select.
+ * @param type the type of driver to select
  * @post Sets the driver so GetCurrentDriver() returns it too.
  */
 Driver *DriverFactoryBase::SelectDriver(const char *name, Driver::Type type)
@@ -144,6 +145,8 @@ Driver *DriverFactoryBase::SelectDriver(const char *name, Driver::Type type)
 /**
  * Register a driver internally, based on its name.
  * @param name the name of the driver.
+ * @param type the type of driver to register
+ * @param priority the priority; how badly do we want this as default?
  * @note an assert() will be trigger if 2 driver with the same name try to register.
  */
 void DriverFactoryBase::RegisterDriver(const char *name, Driver::Type type, int priority)

src/economy.cpp

@@ -855,7 +855,8 @@ static SmallIndustryList _cargo_delivery_destinations;
  * All cargo is delivered to the nearest (Manhattan) industry to the station sign, which is inside the acceptance rectangle and actually accepts the cargo.
  * @param st The station that accepted the cargo
  * @param cargo_type Type of cargo delivered
- * @param nun_pieces Amount of cargo delivered
+ * @param num_pieces Amount of cargo delivered
+ * @param source The source of the cargo
  * @return actually accepted pieces of cargo
  */
 static uint DeliverGoodsToIndustry(const Station *st, CargoID cargo_type, uint num_pieces, IndustryID source)
@@ -903,6 +904,7 @@ static uint DeliverGoodsToIndustry(const Station *st, CargoID cargo_type, uint n
 /**
  * Delivers goods to industries/towns and calculates the payment
  * @param num_pieces amount of cargo delivered
+ * @param cargo_type the type of cargo that is delivered
  * @param dest Station the cargo has been unloaded
  * @param source_tile The origin of the cargo for distance calculation
  * @param days_in_transit Travel time

src/engine_gui.cpp

@@ -237,7 +237,7 @@ StringID GetEngineInfoString(EngineID engine)
  * @param x      Horizontal position to use for drawing the engine.
  * @param y      Vertical position to use for drawing the engine.
  * @param engine Engine to draw.
- * @para, pal    Palette to use for drawing.
+ * @param pal    Palette to use for drawing.
  */
 void DrawVehicleEngine(int x, int y, EngineID engine, SpriteID pal)
 {

src/fileio.cpp

@@ -1028,9 +1028,11 @@ void *ReadFileToMem(const char *filename, size_t *lenp, size_t maxsize)
 /**
  * Scan a single directory (and recursively it's children) and add
  * any graphics sets that are found.
+ * @param fs              the file scanner to add the files to
  * @param extension       the extension of files to search for.
  * @param path            full path we're currently at
  * @param basepath_length from where in the path are we 'based' on the search path
+ * @param recursive       whether to recursively search the sub directories
  */
 static uint ScanPath(FileScanner *fs, const char *extension, const char *path, size_t basepath_length, bool recursive)
 {
@@ -1078,6 +1080,7 @@ static uint ScanPath(FileScanner *fs, const char *extension, const char *path, s
 
 /**
  * Scan the given tar and add graphics sets when it finds one.
+ * @param fs        the file scanner to scan for
  * @param extension the extension of files to search for.
  * @param tar       the tar to search in.
  */
@@ -1104,6 +1107,7 @@ static uint ScanTar(FileScanner *fs, const char *extension, TarFileList::iterato
  * @param extension the extension of files to search for.
  * @param sd        the sub directory to search in.
  * @param tars      whether to search in the tars too.
+ * @param recursive whether to search recursively
  * @return the number of found files, i.e. the number of times that
  *         AddFile returned true.
  */
@@ -1132,6 +1136,7 @@ uint FileScanner::Scan(const char *extension, Subdirectory sd, bool tars, bool r
  * Scan for files with the given extention in the given search path.
  * @param extension the extension of files to search for.
  * @param directory the sub directory to search in.
+ * @param recursive whether to search recursively
  * @return the number of found files, i.e. the number of times that
  *         AddFile returned true.
  */

src/gamelog.cpp

@@ -107,6 +107,7 @@ static void AddDebugText(char *buf, const char *s, ...)
 
 
 /** Prints GRF filename if found
+ * @param buf The location in the _dbgofs buffer to draw
  * @param grfid GRF which filename to print
  */
 static void PrintGrfFilename(char *buf, uint grfid)
@@ -119,6 +120,7 @@ static void PrintGrfFilename(char *buf, uint grfid)
 }
 
 /** Prints GRF ID, checksum and filename if found
+ * @param buf The location in the _dbgofs buffer to draw
  * @param grfid GRF ID
  * @param md5sum array of md5sum to print
  */
@@ -150,7 +152,10 @@ static const char *la_text[] = {
 assert_compile(lengthof(la_text) == GLAT_END);
 
 
-/** Prints active gamelog */
+/**
+ * Prints active gamelog
+ * @param proc the procedure to draw with
+ */
 void GamelogPrint(GamelogPrintProc *proc)
 {
 	char buf[GAMELOG_BUF_LEN];
@@ -359,7 +364,6 @@ bool GamelogTestEmergency()
 }
 
 /** Logs a change in game revision
- * @param revision new revision string
  */
 void GamelogRevision()
 {
@@ -481,7 +485,8 @@ static void GamelogGRFBug(uint32 grfid, byte bug, uint64 data)
  * Ensures this is logged only once for each GRF and engine type
  * This check takes some time, but it is called pretty seldom, so it
  * doesn't matter that much (ideally it shouldn't be called at all).
- * @param engine engine to log
+ * @param grfid the broken NewGRF
+ * @param internal_id the internal ID of whatever's broken in the NewGRF
  * @return true iff a unique record was done
  */
 bool GamelogGRFBugReverse(uint32 grfid, uint16 internal_id)

src/genworld.cpp

@@ -262,6 +262,7 @@ void HandleGeneratingWorldAbortion()
  * @param mode The mode of world generation (see GenerateWorldModes).
  * @param size_x The X-size of the map.
  * @param size_y The Y-size of the map.
+ * @param reset_settings Whether to reset the game configuration (used for restart)
  */
 void GenerateWorld(GenerateWorldMode mode, uint size_x, uint size_y, bool reset_settings)
 {

src/gfx.cpp

@@ -435,6 +435,7 @@ static int GetStringWidth(const UChar *str)
  *               case a right-to-left language is chosen this is inverted so it
  *               will be drawn in the right direction.
  * @param underline Whether to underline what has been drawn or not.
+ * @param truncate  Whether to truncate the string or not.
  *
  * @return In case of left or center alignment the right most pixel we have drawn to.
  *         In case of right alignment the left most pixel we have drawn to.

src/group.h

@@ -70,6 +70,7 @@ static inline uint GetGroupArraySize()
 /**
  * Get the number of engines with EngineID id_e in the group with GroupID
  * id_g
+ * @param company The company the group belongs to
  * @param id_g The GroupID of the group used
  * @param id_e The EngineID of the engine to count
  * @return The number of engines with EngineID id_e in the group

src/industry.h

@@ -74,7 +74,7 @@ struct Industry : IndustryPool::PoolItem<&_industry_pool> {
 
 	/**
 	 * Get the industry of the given tile
-	 * @param t the tile to get the industry from
+	 * @param tile the tile to get the industry from
 	 * @pre IsTileType(t, MP_INDUSTRY)
 	 * @return the industry
 	 */

src/industry_map.h

@@ -304,6 +304,7 @@ static inline void SetIndustryTriggers(TileIndex tile, byte triggers)
  * @param index  the industry this tile belongs to
  * @param gfx    the graphics to use for the tile
  * @param random the random value
+ * @param wc     the water class for this industry; only useful when build on water
  */
 static inline void MakeIndustry(TileIndex t, IndustryID index, IndustryGfx gfx, uint8 random, WaterClass wc)
 {

src/map.cpp

@@ -264,9 +264,11 @@ bool CircularTileSearch(TileIndex *tile, uint size, TestTileOnSearchProc proc, v
  * Every tile will be tested by means of the callback function proc,
  * which will determine if yes or no the given tile meets criteria of search.
  * @param tile to start the search from. Upon completion, it will return the tile matching the search
- * @param radius: How many tiles to search outwards. Note: This is a radius and thus different
+ * @param radius How many tiles to search outwards. Note: This is a radius and thus different
  *                from the size parameter of the other CircularTileSearch function, which is a diameter.
- * @param proc: callback testing function pointer.
+ * @param w the width of the inner rectangle
+ * @param h the height of the inner rectangle
+ * @param proc callback testing function pointer.
  * @param user_data to be passed to the callback function. Depends on the implementation
  * @return result of the search
  * @pre proc != NULL

src/music/qtmidi.cpp

@@ -50,7 +50,7 @@ enum {
  * Sets the @c OSType of a given file to @c 'Midi', but only if it's not
  * already set.
  *
- * @param *spec A @c FSSpec structure referencing a file.
+ * @param *ref A @c FSSpec structure referencing a file.
  */
 static void SetMIDITypeIfNeeded(const FSRef *ref)
 {

src/newgrf_industries.cpp

@@ -152,6 +152,7 @@ static uint32 GetCountAndDistanceOfClosestInstance(byte param_setID, byte layout
 }
 
 /** This function implements the industries variables that newGRF defines.
+ * @param object the object that we want to query
  * @param variable that is queried
  * @param parameter unused
  * @param available will return false if ever the variable asked for does not exist

src/newgrf_spritegroup.h

@@ -225,7 +225,7 @@ protected:
 struct CallbackResultSpriteGroup : SpriteGroup {
 	/**
 	 * Creates a spritegroup representing a callback result
-	 * @param result The value that was used to represent this callback result
+	 * @param value The value that was used to represent this callback result
 	 */
 	CallbackResultSpriteGroup(uint16 value) :
 		SpriteGroup(SGT_CALLBACK),

src/newgrf_text.cpp

@@ -382,7 +382,7 @@ const char *GetGRFStringPtr(uint16 stringid)
  * of the current language set by the user.
  * This function is called after the user changed language,
  * from strings.cpp:ReadLanguagePack
- * @param langauge_id iso code of current selection
+ * @param language_id iso code of current selection
  */
 void SetCurrentGrfLangID(byte language_id)
 {
@@ -529,7 +529,9 @@ void RewindTextRefStack()
 /**
  * FormatString for NewGRF specific "magic" string control codes
  * @param scc   the string control code that has been read
- * @param stack the current "stack"
+ * @param buff  the buffer we're writing to
+ * @param str   the string that we need to write
+ * @param argv  the OpenTTD stack of values
  * @return the string control code to "execute" now
  */
 uint RemapNewGRFStringControlCode(uint scc, char **buff, const char **str, int64 *argv)

src/news_gui.cpp

@@ -652,6 +652,7 @@ static void MoveToNextItem()
  * @param ref1     Reference 1 to some object: Used for a possible viewport, scrolling after clicking on the news, and for deleteing the news when the object is deleted.
  * @param reftype2 Type of ref2
  * @param ref2     Reference 2 to some object: Used for scrolling after clicking on the news, and for deleteing the news when the object is deleted.
+ * @param free_data Pointer to data that must be freed once the news message is cleared
  *
  * @see NewsSubype
  */

src/order_base.h

@@ -79,7 +79,7 @@ public:
 
 	/**
 	 * Makes this order a Go To Station order.
-	 * @param destsination the station to go to.
+	 * @param destination the station to go to.
 	 */
 	void MakeGoToStation(StationID destination);
 

src/order_cmd.cpp

@@ -1662,6 +1662,7 @@ VehicleOrderID ProcessConditionalOrder(const Order *order, const Vehicle *v)
  * Update the vehicle's destination tile from an order.
  * @param order the order the vehicle currently has
  * @param v the vehicle to update
+ * @param conditional_depth the depth (amount of steps) to go with conditional orders. This to prevent infinite loops.
  */
 bool UpdateOrderDest(Vehicle *v, const Order *order, int conditional_depth)
 {

src/osk_gui.cpp

@@ -346,7 +346,7 @@ static const int INTER_KEY_SPACE = 2; // Number of pixels between two keys.
  * Add a key widget to a row of the keyboard.
  * @param hor     Row container to add key widget to.
  * @param height  Height of the key (all keys in a row should have equal height).
- * @param numhalf Number of 1/2 key widths that this key has.
+ * @param num_half Number of 1/2 key widths that this key has.
  * @param widtype Widget type of the key. Must be either \c NWID_SPACER for an invisible key, or a \c WWT_* widget.
  * @param widnum  Widget number of the key.
  * @param widdata Data value of the key widget.

src/pbs.cpp

@@ -327,7 +327,7 @@ Train *GetTrainForReservation(TileIndex tile, Track track)
  * @param tile The tile
  * @param trackdir The trackdir to test
  * @param include_line_end Should end-of-line tiles be considered safe?
- * @param forbid_90def Don't allow trains to make 90 degree turns
+ * @param forbid_90deg Don't allow trains to make 90 degree turns
  * @return True if it is a safe position
  */
 bool IsSafeWaitingPosition(const Train *v, TileIndex tile, Trackdir trackdir, bool include_line_end, bool forbid_90deg)
@@ -367,7 +367,7 @@ bool IsSafeWaitingPosition(const Train *v, TileIndex tile, Trackdir trackdir, bo
  * @param v the vehicle to test for
  * @param tile The tile
  * @param trackdir The trackdir to test
- * @param forbid_90def Don't allow trains to make 90 degree turns
+ * @param forbid_90deg Don't allow trains to make 90 degree turns
  * @return True if the position is free
  */
 bool IsWaitingPositionFree(const Train *v, TileIndex tile, Trackdir trackdir, bool forbid_90deg)

src/rail.h

@@ -261,7 +261,7 @@ RailType GetBestRailtype(const CompanyID company);
 
 /**
  * Get the rail types the given company can build.
- * @param company the company to get the rail types for.
+ * @param c the company to get the rail types for.
  * @return the rail types.
  */
 RailTypes GetCompanyRailtypes(const CompanyID c);

src/rail_map.h

@@ -132,7 +132,7 @@ static inline void SetRailType(TileIndex t, RailType r)
 
 /**
  * Gets the track bits of the given tile
- * @param t the tile to get the track bits from
+ * @param tile the tile to get the track bits from
  * @return the track bits of the tile
  */
 static inline TrackBits GetTrackBits(TileIndex tile)

src/road_cmd.cpp

@@ -174,6 +174,7 @@ bool CheckAllowRemoveRoad(TileIndex tile, RoadBits remove, Owner owner, RoadType
  * @param pieces roadbits to remove
  * @param rt roadtype to remove
  * @param crossing_check should we check if there is a tram track when we are removing road from crossing?
+ * @param town_check should we check if the town allows removal?
  */
 static CommandCost RemoveRoad(TileIndex tile, DoCommandFlag flags, RoadBits pieces, RoadType rt, bool crossing_check, bool town_check = true)
 {

src/road_map.h

@@ -364,7 +364,7 @@ static inline DiagDirection GetRoadDepotDirection(TileIndex t)
  * on the orientation of the tunnel or bridge.
  * @param tile the tile to get the road bits for
  * @param rt   the road type to get the road bits form
- * @param stbe whether to return straight road bits for tunnels/bridges.
+ * @param straight_tunnel_bridge_entrance whether to return straight road bits for tunnels/bridges.
  * @return the road bits of the given tile
  */
 RoadBits GetAnyRoadBits(TileIndex tile, RoadType rt, bool straight_tunnel_bridge_entrance = false);

src/roadveh_gui.cpp

@@ -124,9 +124,9 @@ void DrawRoadVehDetails(const Vehicle *v, int left, int right, int y)
 /**
  * Draws an image of a road vehicle chain
  * @param v Front vehicle
- + @param x x Position to start at
+ * @param x x Position to start at
  * @param y y Position to draw at
- * @param seletion Selected vehicle to draw a border around
+ * @param selection Selected vehicle to draw a border around
  * @param max_width Number of pixels space for drawing
  */
 void DrawRoadVehImage(const Vehicle *v, int x, int y, VehicleID selection, int max_width)

src/saveload/oldloader.cpp

@@ -209,6 +209,7 @@ static void InitLoading(LoadgameState *ls)
 /**
  * Verifies the title has a valid checksum
  * @param title title and checksum
+ * @param len   the length of the title to read/checksum
  * @return true iff the title is valid
  * @note the title (incl. checksum) has to be at least 41/49 (HEADER_SIZE) bytes long!
  */

src/saveload/saveload.cpp

@@ -1780,6 +1780,7 @@ void WaitTillSaved()
  * handled. It opens the savegame, selects format and checks versions
  * @param filename The name of the savegame being created/loaded
  * @param mode Save or load. Load can also be a TTD(Patch) game. Use SL_LOAD, SL_OLD_LOAD or SL_SAVE
+ * @param sb The sub directory to save the savegame in
  * @param threaded True when threaded saving is allowed
  * @return Return the results of the action. SL_OK, SL_ERROR or SL_REINIT ("unload" the game)
  */

src/script/script_scanner.hpp

@@ -31,7 +31,7 @@ public:
 
 	/**
 	 * Rescan for scripts.
-	 * @param info_flie_name The name of the 'info.nut' file.
+	 * @param info_file_name The name of the 'info.nut' file.
 	 * @param search_dir The subdirecotry to search for scripts.
 	 */
 	void ScanScriptDir(const char *info_file_name, Subdirectory search_dir);

src/script/squirrel.hpp

@@ -144,6 +144,7 @@ public:
 
 	/**
 	 * Creates a class instance.
+	 * @param vm The VM to create the class instance for
 	 * @param class_name The name of the class of which we create an instance.
 	 * @param real_instance The instance to the real class, if it represents a real class.
 	 * @param instance Returning value with the pointer to the instance.

src/settings.cpp

@@ -301,7 +301,7 @@ static void make_manyofmany(char *buf, const char *last, const char *many, uint3
 
 /** Convert a string representation (external) of a setting to the internal rep.
  * @param desc SettingDesc struct that holds all information about the variable
- * @param str input string that will be parsed based on the type of desc
+ * @param orig_str input string that will be parsed based on the type of desc
  * @return return the parsed value of the setting */
 static const void *string_to_val(const SettingDescBase *desc, const char *orig_str)
 {
@@ -605,9 +605,8 @@ static void ini_save_settings(IniFile *ini, const SettingDesc *sd, const char *g
  * saved and a callback function should be defined that will take over the
  * list-handling and store the data itself somewhere.
  * @param ini IniFile handle to the ini file with the source data
- * @param grpname character string identifying the section-header of the ini
+ * @param grpname character string identifying the section-header of the ini file that will be parsed
- * file that will be parsed
+ * @param list new list with entries of the given section
- * entries of the given section
  */
 static void ini_load_setting_list(IniFile *ini, const char *grpname, StringList *list)
 {

src/spritecache.cpp

@@ -494,6 +494,7 @@ void *AllocSprite(size_t mem_req)
  * @param sprite ID of loaded sprite
  * @param requested requested sprite type
  * @param available available sprite type
+ * @param sc the currently known sprite cache for the requested sprite
  * @return fallback sprite
  * @note this function will do usererror() in the case the fallback sprite isn't available */
 static void *HandleInvalidSpriteRequest(SpriteID sprite, SpriteType requested, SpriteCache *sc)

src/station_cmd.cpp

@@ -114,10 +114,8 @@ typedef bool (*CMSAMatcher)(TileIndex tile);
 /**
  * Counts the numbers of tiles matching a specific type in the area around
  * @param tile the center tile of the 'count area'
- * @param type the type of tile searched for
+ * @param cmp the comparator/matcher (@see CMSAMatcher)
- * @param industry when type == MP_INDUSTRY, the type of the industry,
+ * @return the number of matching tiles around
- *                 in all other cases this parameter is ignored
- * @return the result the noumber of matching tiles around
  */
 static int CountMapSquareAround(TileIndex tile, CMSAMatcher cmp)
 {
@@ -660,6 +658,7 @@ CommandCost ClearTile_Station(TileIndex tile, DoCommandFlag flags);
  * @param invalid_dirs prohibited directions (set of DiagDirections)
  * @param station StationID to be queried and returned if available
  * @param check_clear if clearing tile should be performed (in wich case, cost will be added)
+ * @param rt The rail type to check for (overbuilding rail stations over rail)
  * @return the cost in case of success, or an error code if it failed.
  */
 CommandCost CheckFlatLandBelow(TileIndex tile, uint w, uint h, DoCommandFlag flags, uint invalid_dirs, StationID *station, bool check_clear = true, RailType rt = INVALID_RAILTYPE)
@@ -928,7 +927,7 @@ CommandCost FindJoiningStation(StationID existing_station, StationID station_to_
  * @param waypoint_to_join the waypoint to join to
  * @param adjacent whether adjacent waypoints are allowed
  * @param ta the area of the newly build waypoint
- * @param st 'return' pointer for the found waypoint
+ * @param wp 'return' pointer for the found waypoint
  * @return command cost with the error or 'okay'
  */
 CommandCost FindJoiningWaypoint(StationID existing_waypoint, StationID waypoint_to_join, bool adjacent, TileArea ta, Waypoint **wp)
@@ -2971,8 +2970,7 @@ CommandCost CmdRenameStation(TileIndex tile, DoCommandFlag flags, uint32 p1, uin
  * @param tile North tile of producer
  * @param w_prod X extent of producer
  * @param h_prod Y extent of producer
- *
+ * @param stations The list to store the stations in
- * @return: Set of found stations
  */
 void FindStationsAroundTiles(TileIndex tile, int w_prod, int h_prod, StationList *stations)
 {

src/station_gui.cpp

@@ -750,6 +750,7 @@ SpriteID GetCargoSprite(CargoID i)
  * @param waiting number of waiting units
  * @param x x on-screen coordinate where to start with drawing icons
  * @param y y coordinate
+ * @param width the width of the view
  */
 static void DrawCargoIcons(CargoID i, uint waiting, int x, int y, uint width)
 {
@@ -1128,9 +1129,7 @@ static bool AddNearbyStation(TileIndex tile, void *user_data)
  * Circulate around the to-be-built station to find stations we could join.
  * Make sure that only stations are returned where joining wouldn't exceed
  * station spread and are our own station.
- * @param tile Base tile of the to-be-built station
+ * @param ta Base tile area of the to-be-built station
- * @param w Width of the to-be-built station
- * @param h Height of the to-be-built station
  * @param distant_join Search for adjacent stations (false) or stations fully
  *                     within station spread
  * @tparam T the type of station to look for
@@ -1308,8 +1307,7 @@ static const WindowDesc _select_station_desc(
 /**
  * Check whether we need to show the station selection window.
  * @param cmd Command to build the station.
- * @param w Width of the to-be-built station
+ * @param ta Tile area of the to-be-built station
- * @param h Height of the to-be-built station
  * @tparam T the type of station
  * @return whether we need to show the station selection window.
  */

src/table/build_industry.h

@@ -1575,7 +1575,7 @@ static const IndustrySpec _origin_industry_specs[NEW_INDUSTRYOFFSET] = {
  * @param c2  second cargo
  * @param ca3 acceptance of third cargo
  * @param c3  and third cargo. Those three are in an array
- * @param s1  slope refused upon choosing a place to build
+ * @param sl  slope refused upon choosing a place to build
  * @param a1  animation frame on production
  * @param a2  next frame of animation
  * @param a3  chooses between animation or construction state

src/terraform_gui.cpp

@@ -110,8 +110,9 @@ static void GenerateRockyArea(TileIndex end, TileIndex start)
 
 /**
  * A central place to handle all X_AND_Y dragged GUI functions.
- * @param e WindowEvent variable holding in its higher bits (excluding the lower
+ * @param proc       Procedure related to the dragging
- * 4, since that defined the X_Y drag) the type of action to be performed
+ * @param start_tile Begin of the dragging
+ * @param end_tile   End of the dragging
  * @return Returns true if the action was found and handled, and false otherwise. This
  * allows for additional implements that are more local. For example X_Y drag
  * of convertrail which belongs in rail_gui.cpp and not terraform_gui.cpp

src/tile_map.cpp

@@ -78,7 +78,7 @@ uint GetTileZ(TileIndex tile)
 
 /**
  * Get top height of the tile
- * @param tile Tile to compute height of
+ * @param t Tile to compute height of
  * @return Maximum height of the tile */
 uint GetTileMaxZ(TileIndex t)
 {

src/town_cmd.cpp

@@ -1485,8 +1485,10 @@ void UpdateTownMaxPass(Town *t)
  * @param t The town
  * @param tile Where to put it
  * @param townnameparts The town name
- * @param size_mode How the size should be determined
  * @param size Parameter for size determination
+ * @param size_mode How the size should be determined
+ * @param city whether to build a city or town
+ * @param layout the (road) layout of the town
  */
 static void DoCreateTown(Town *t, TileIndex tile, uint32 townnameparts, TownSize size, bool city, TownLayout layout)
 {
@@ -1726,6 +1728,7 @@ static bool FindNearestEmptyLand(TileIndex tile, void *user_data)
  * flat spot.
  *
  * @param tile Start looking from this spot.
+ * @param layout the road layout to search for
  * @return tile that was found
  */
 static TileIndex FindNearestGoodCoastalTownSpot(TileIndex tile, TownLayout layout)
@@ -1840,8 +1843,8 @@ HouseZonesBits GetTownRadiusGroup(const Town *t, TileIndex tile)
 
 /**
  * Clears tile and builds a house or house part.
- * @param t tile index
+ * @param tile tile index
- * @param tid Town index
+ * @param t The town to clear the house for
  * @param counter of construction step
  * @param stage of construction (used for drawing)
  * @param type of house. Index into house specs array
@@ -1865,7 +1868,7 @@ static inline void ClearMakeHouseTile(TileIndex tile, Town *t, byte counter, byt
 /**
  * Write house information into the map. For houses > 1 tile, all tiles are marked.
  * @param t tile index
- * @param tid Town index
+ * @param town The town related to this house
  * @param counter of construction step
  * @param stage of construction (used for drawing)
  * @param type of house. Index into house specs array

src/train_gui.cpp

@@ -64,9 +64,9 @@ void CcBuildLoco(bool success, TileIndex tile, uint32 p1, uint32 p2)
 /**
  * Draws an image of a whole train
  * @param v Front vehicle
- + @param x x Position to start at
+ * @param x x Position to start at
  * @param y y Position to draw at
- * @param seletion Selected vehicle to draw a frame around
+ * @param selection Selected vehicle to draw a frame around
  * @param max_width Number of pixels space for drawing
  * @param skip Number of pixels to skip at the front (for scrolling)
  */

src/tree_cmd.cpp

@@ -74,7 +74,7 @@ static bool CanPlantTreesOnTile(TileIndex tile, bool allow_desert)
  * @pre the tile must be suitable for trees.
  *
  * @param tile where to plant the trees.
- * @param type The type of the tree
+ * @param treetype The type of the tree
  * @param count the number of trees (minus 1)
  * @param growth the growth status
  */

src/tree_map.h

@@ -268,7 +268,7 @@ static inline void SetTreeCounter(TileIndex t, uint c)
  *
  * @param t The tile to make a tree-tile from
  * @param type The type of the tree
- * @param set the number of trees
+ * @param count the number of trees
  * @param growth the growth status
  * @param ground the ground type
  * @param density the density (not the number of trees)

src/tunnelbridge_cmd.cpp

@@ -753,7 +753,7 @@ static CommandCost ClearTile_TunnelBridge(TileIndex tile, DoCommandFlag flags)
  * @param psid Image and palette of a bridge pillar.
  * @param ti #TileInfo of current bridge-middle-tile.
  * @param axis Orientation of bridge.
- * @param type Bridge type.
+ * @param drawfarpillar Whether to draw the pillar at the back
  * @param x Sprite X position of front pillar.
  * @param y Sprite Y position of front pillar.
  * @param z_bridge Absolute height of bridge bottom.

src/unmovable_map.h

@@ -155,7 +155,7 @@ static inline byte GetCompanyHQSection(TileIndex t)
 /**
  * Set the 'section' of the HQ.
  * @param t a tile of the HQ.
- * param section to be set.
+ * @param section to be set.
  * @pre IsTileType(t, MP_UNMOVABLE) && IsCompanyHQ(t)
  */
 static inline void SetCompanyHQSection(TileIndex t, uint8 section)

src/vehicle_cmd.cpp

@@ -506,6 +506,7 @@ CommandCost CmdCloneVehicle(TileIndex tile, DoCommandFlag flags, uint32 p1, uint
  * @param service should the vehicles only get service in the depots
  * @param owner owner of the vehicles to send
  * @param vlw_flag tells what kind of list requested the goto depot
+ * @param id general purpose id whoms meaning is given by @c vlw_flag; e.g. StationID for station lists
  * @return 0 for success and CMD_ERROR if no vehicle is able to go to depot
  */
 CommandCost SendAllVehiclesToDepot(VehicleType type, DoCommandFlag flags, bool service, Owner owner, uint16 vlw_flag, uint32 id)

src/vehicle_gui.cpp

@@ -242,6 +242,7 @@ static RefitList *BuildRefitList(const Vehicle *v)
  * @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
+ * @param right the right most position to draw
  * @return the refit option that is hightlighted, NULL if none
  */
 static RefitOption *DrawVehicleRefitWindow(const RefitList *list, int sel, uint pos, uint rows, uint delta, uint right)
@@ -433,6 +434,7 @@ static const WindowDesc _vehicle_refit_desc(
 /** Show the refit window for a vehicle
  * @param *v The vehicle to show the refit window for
  * @param order of the vehicle ( ? )
+ * @param parent the parent window of the refit window
  */
 void ShowVehicleRefitWindow(const Vehicle *v, VehicleOrderID order, Window *parent)
 {
@@ -782,9 +784,9 @@ static void DrawSmallOrderList(const Vehicle *v, int left, int right, int y)
 /**
  * Draws an image of a vehicle chain
  * @param v Front vehicle
- + @param x x Position to start at
+ * @param x x Position to start at
  * @param y y Position to draw at
- * @param seletion Selected vehicle to draw a frame around
+ * @param selection Selected vehicle to draw a frame around
  * @param max_width Number of pixels space for drawing
  * @param skip Number of pixels to skip at the front (for scrolling)
  */

src/waypoint_cmd.cpp

@@ -157,6 +157,7 @@ CommandCost ClearTile_Station(TileIndex tile, DoCommandFlag flags);
  * Check whether the given tile is suitable for a waypoint.
  * @param tile the tile to check for suitability
  * @param axis the axis of the waypoint
+ * @param waypoint Waypoint the waypoint to check for is already joined to. If we find another waypoint it can join to it will throw an error.
  */
 static CommandCost IsValidTileForWaypoint(TileIndex tile, Axis axis, StationID *waypoint)
 {

src/widget_type.h

@@ -642,8 +642,8 @@ static inline NWidgetPart SetResize(int16 dx, int16 dy)
 
 /**
  * Widget part function for setting the minimal size.
- * @param dx Horizontal minimal size.
+ * @param x Horizontal minimal size.
- * @param dy Vertical minimal size.
+ * @param y Vertical minimal size.
  * @ingroup NestedWidgetParts
  */
 static inline NWidgetPart SetMinimalSize(int16 x, int16 y)

src/window.cpp

@@ -2479,6 +2479,7 @@ void SetWindowClassesDirty(WindowClass cls)
 /**
  * Mark window data as invalid (in need of re-computing)
  * @param w Window with invalid data
+ * @param data The data to invalidate with
  */
 void InvalidateThisWindowData(Window *w, int data)
 {
@@ -2490,6 +2491,7 @@ void InvalidateThisWindowData(Window *w, int data)
  * Mark window data of the window of a given class and specific window number as invalid (in need of re-computing)
  * @param cls Window class
  * @param number Window number within the class
+ * @param data The data to invalidate with
  */
 void InvalidateWindowData(WindowClass cls, WindowNumber number, int data)
 {
@@ -2502,6 +2504,7 @@ void InvalidateWindowData(WindowClass cls, WindowNumber number, int data)
 /**
  * Mark window data of all windows of a given class as invalid (in need of re-computing)
  * @param cls Window class
+ * @param data The data to invalidate with
  */
 void InvalidateWindowClassesData(WindowClass cls, int data)
 {