# HG changeset patch # User Charles Pigott # Date 2018-10-28 02:17:36 # Node ID 7b8669afd1db843ccfe5fc87457894f3a8cabd87 # Parent 731ae130079943651f7fbb69ae3c8e77ee6fa1b6 Doc: Lots and lots of doxymentation fixes diff --git a/Doxyfile b/Doxyfile --- a/Doxyfile +++ b/Doxyfile @@ -14,7 +14,7 @@ PROJECT_NUMBER = PROJECT_BRIEF = PROJECT_LOGO = OUTPUT_DIRECTORY = docs/source/ -CREATE_SUBDIRS = NO +CREATE_SUBDIRS = YES ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES @@ -72,7 +72,7 @@ EXTRACT_PACKAGE = NO EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = YES -EXTRACT_ANON_NSPACES = NO +EXTRACT_ANON_NSPACES = YES HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO @@ -130,7 +130,6 @@ RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = */3rdparty \ - */.svn \ */script/api EXCLUDE_SYMBOLS = EXAMPLE_PATH = @@ -183,7 +182,7 @@ DOCSET_FEEDNAME = "Doxygen genera DOCSET_BUNDLE_ID = org.doxygen.Project DOCSET_PUBLISHER_ID = org.doxygen.Publisher DOCSET_PUBLISHER_NAME = Publisher -GENERATE_HTMLHELP = YES +GENERATE_HTMLHELP = NO CHM_FILE = HHC_LOCATION = GENERATE_CHI = NO diff --git a/src/aircraft_cmd.cpp b/src/aircraft_cmd.cpp --- a/src/aircraft_cmd.cpp +++ b/src/aircraft_cmd.cpp @@ -248,7 +248,7 @@ void GetAircraftSpriteSize(EngineID engi * @param flags type of operation. * @param e the engine to build. * @param data unused. - * @param ret[out] the vehicle that has been built. + * @param[out] ret the vehicle that has been built. * @return the cost of this operation or an error. */ CommandCost CmdBuildAircraft(TileIndex tile, DoCommandFlag flags, const Engine *e, uint16 data, Vehicle **ret) @@ -694,9 +694,9 @@ int GetTileHeightBelowAircraft(const Veh * When the maximum is reached the vehicle should consider descending. * When the minimum is reached the vehicle should consider ascending. * - * @param v The vehicle to get the flight levels for. - * @param [out] min_level The minimum bounds for flight level. - * @param [out] max_level The maximum bounds for flight level. + * @param v The vehicle to get the flight levels for. + * @param[out] min_level The minimum bounds for flight level. + * @param[out] max_level The maximum bounds for flight level. */ void GetAircraftFlightLevelBounds(const Vehicle *v, int *min_level, int *max_level) { @@ -728,7 +728,7 @@ void GetAircraftFlightLevelBounds(const /** * Gets the maximum 'flight level' for the holding pattern of the aircraft, - * in pixels 'z_pos' 0, depending on terrain below.. + * in pixels 'z_pos' 0, depending on terrain below. * * @param v The aircraft that may or may not need to decrease its altitude. * @return Maximal aircraft holding altitude, while in normal flight, in pixels. @@ -1889,7 +1889,7 @@ static bool FreeTerminal(Aircraft *v, by /** * Get the number of terminals at the airport. - * @param afc Airport description. + * @param apc Airport description. * @return Number of terminals. */ static uint GetNumTerminals(const AirportFTAClass *apc) diff --git a/src/autoreplace_cmd.cpp b/src/autoreplace_cmd.cpp --- a/src/autoreplace_cmd.cpp +++ b/src/autoreplace_cmd.cpp @@ -32,7 +32,6 @@ extern void ChangeVehicleViewWindow(Vehi * Figure out if two engines got at least one type of cargo in common (refitting if needed) * @param engine_a one of the EngineIDs * @param engine_b the other EngineID - * @param type the type of the engines * @return true if they can both carry the same type of cargo (or at least one of them got no capacity at all) */ static bool EnginesHaveCargoInCommon(EngineID engine_a, EngineID engine_b) @@ -237,7 +236,7 @@ static CargoID GetNewCargoTypeForReplace * @param v The vehicle to find a replacement for * @param c The vehicle's owner (it's faster to forward the pointer than refinding it) * @param always_replace Always replace, even if not old. - * @param [out] e the EngineID of the replacement. INVALID_ENGINE if no replacement is found + * @param[out] e the EngineID of the replacement. INVALID_ENGINE if no replacement is found * @return Error if the engine to build is not available */ static CommandCost GetNewEngineType(const Vehicle *v, const Company *c, bool always_replace, EngineID &e) diff --git a/src/autoreplace_gui.cpp b/src/autoreplace_gui.cpp --- a/src/autoreplace_gui.cpp +++ b/src/autoreplace_gui.cpp @@ -81,7 +81,7 @@ class ReplaceVehicleWindow : public Wind EngineID sel_engine[2]; ///< Selected engine left and right. GUIEngineList engines[2]; ///< Left and right list of engines. bool replace_engines; ///< If \c true, engines are replaced, if \c false, wagons are replaced (only for trains). - bool reset_sel_engine; ///< Also reset #sel_engine while updating left and/or right (#update_left and/or #update_right) and no valid engine selected. + bool reset_sel_engine; ///< Also reset #sel_engine while updating left and/or right and no valid engine selected. GroupID sel_group; ///< Group selected to replace. int details_height; ///< Minimal needed height of the details panels (found so far). byte sort_criteria; ///< Criteria of sorting vehicles. diff --git a/src/blitter/32bpp_anim_sse4.cpp b/src/blitter/32bpp_anim_sse4.cpp --- a/src/blitter/32bpp_anim_sse4.cpp +++ b/src/blitter/32bpp_anim_sse4.cpp @@ -7,7 +7,7 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file 32bpp_sse4_anim.cpp Implementation of the SSE4 32 bpp blitter with animation support. */ +/** @file 32bpp_anim_sse4.cpp Implementation of the SSE4 32 bpp blitter with animation support. */ #ifdef WITH_SSE diff --git a/src/blitter/32bpp_anim_sse4.hpp b/src/blitter/32bpp_anim_sse4.hpp --- a/src/blitter/32bpp_anim_sse4.hpp +++ b/src/blitter/32bpp_anim_sse4.hpp @@ -7,7 +7,7 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file 32bpp_sse4_anim.hpp A SSE4 32 bpp blitter with animation support. */ +/** @file 32bpp_anim_sse4.hpp A SSE4 32 bpp blitter with animation support. */ #ifndef BLITTER_32BPP_SSE4_ANIM_HPP #define BLITTER_32BPP_SSE4_ANIM_HPP diff --git a/src/blitter/32bpp_sse_type.h b/src/blitter/32bpp_sse_type.h --- a/src/blitter/32bpp_sse_type.h +++ b/src/blitter/32bpp_sse_type.h @@ -7,10 +7,10 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file 32bpp_sse_type.hpp Types related to SSE 32 bpp blitter. */ +/** @file 32bpp_sse_type.h Types related to SSE 32 bpp blitter. */ -#ifndef BLITTER_32BPP_SSE_TYPE_HPP -#define BLITTER_32BPP_SSE_TYPE_HPP +#ifndef BLITTER_32BPP_SSE_TYPE_H +#define BLITTER_32BPP_SSE_TYPE_H #ifdef WITH_SSE @@ -55,4 +55,4 @@ typedef union ALIGN(16) um128i { #define TRANSPARENT_NOM_BASE _mm_setr_epi16(256, 256, 256, 256, 256, 256, 256, 256) #endif /* WITH_SSE */ -#endif /* BLITTER_32BPP_SSE_TYPE_HPP */ +#endif /* BLITTER_32BPP_SSE_TYPE_H */ diff --git a/src/bridge_map.cpp b/src/bridge_map.cpp --- a/src/bridge_map.cpp +++ b/src/bridge_map.cpp @@ -56,7 +56,7 @@ TileIndex GetSouthernBridgeEnd(TileIndex /** * Starting at one bridge end finds the other bridge end - * @param t the bridge ramp tile to find the other bridge ramp for + * @param tile the bridge ramp tile to find the other bridge ramp for */ TileIndex GetOtherBridgeEnd(TileIndex tile) { @@ -66,7 +66,7 @@ TileIndex GetOtherBridgeEnd(TileIndex ti /** * Get the height ('z') of a bridge. - * @param tile the bridge ramp tile to get the bridge height from + * @param t the bridge ramp tile to get the bridge height from * @return the height of the bridge. */ int GetBridgeHeight(TileIndex t) diff --git a/src/cargopacket.cpp b/src/cargopacket.cpp --- a/src/cargopacket.cpp +++ b/src/cargopacket.cpp @@ -602,7 +602,7 @@ uint VehicleCargoList::Reassign#if expression - TOKEN_AND, ///< '&&' within #if expression - TOKEN_DEFINED, ///< 'defined' within #if expression - TOKEN_OPEN, ///< '(' within #if expression - TOKEN_CLOSE, ///< ')' within #if expression - TOKEN_NOT, ///< '!' within #if expression - TOKEN_ZERO, ///< '0' within #if expression - TOKEN_INCLUDE, ///< (#)include in code + TOKEN_DEFINE, ///< \c \#define in code + TOKEN_IF, ///< \c \#if in code + TOKEN_IFDEF, ///< \c \#ifdef in code + TOKEN_IFNDEF, ///< \c \#ifndef in code + TOKEN_ELIF, ///< \c \#elif in code + TOKEN_ELSE, ///< \c \#else in code + TOKEN_ENDIF, ///< \c \#endif in code + TOKEN_UNDEF, ///< \c \#undef in code + TOKEN_OR, ///< '||' within \c \#if expression + TOKEN_AND, ///< '&&' within \c \#if expression + TOKEN_DEFINED, ///< 'defined' within \c \#if expression + TOKEN_OPEN, ///< '(' within \c \#if expression + TOKEN_CLOSE, ///< ')' within \c \#if expression + TOKEN_NOT, ///< '!' within \c \#if expression + TOKEN_ZERO, ///< '0' within \c \#if expression + TOKEN_INCLUDE, ///< \c \#include in code }; /** Mapping from a C-style keyword representation to a Token. */ @@ -681,8 +681,8 @@ bool ExpressionOr(Lexer *lexer, StringSe /** Enumerator to tell how long to ignore 'stuff'. */ enum Ignore { NOT_IGNORE, ///< No ignoring. - IGNORE_UNTIL_ELSE, ///< Ignore till a #else is reached. - IGNORE_UNTIL_ENDIF, ///< Ignore till a #endif is reached. + IGNORE_UNTIL_ELSE, ///< Ignore till a \c \#else is reached. + IGNORE_UNTIL_ENDIF, ///< Ignore till a \c \#endif is reached. }; /** diff --git a/src/dock_gui.cpp b/src/dock_gui.cpp --- a/src/dock_gui.cpp +++ b/src/dock_gui.cpp @@ -56,8 +56,8 @@ void CcPlaySound_SPLAT_WATER(const Comma /** * Gets the other end of the aqueduct, if possible. - * @param tile_from The begin tile for the aqueduct. - * @param [out] tile_to The tile till where to show a selection for the aqueduct. + * @param tile_from The begin tile for the aqueduct. + * @param[out] tile_to The tile till where to show a selection for the aqueduct. * @return The other end of the aqueduct, or otherwise a tile in line with the aqueduct to cause the right error message. */ static TileIndex GetOtherAqueductEnd(TileIndex tile_from, TileIndex *tile_to = NULL) diff --git a/src/economy.cpp b/src/economy.cpp --- a/src/economy.cpp +++ b/src/economy.cpp @@ -1242,7 +1242,6 @@ Money CargoPayment::PayTransfer(const Ca /** * Prepare the vehicle to be unloaded. - * @param curr_station the station where the consist is at the moment * @param front_v the vehicle to be unloaded */ void PrepareUnload(Vehicle *front_v) diff --git a/src/engine.cpp b/src/engine.cpp --- a/src/engine.cpp +++ b/src/engine.cpp @@ -573,7 +573,7 @@ static bool IsWagon(EngineID index) } /** - * Update #reliability of engine \a e, (if needed) update the engine GUIs. + * Update #Engine::reliability and (if needed) update the engine GUIs. * @param e %Engine to update. */ static void CalcEngineReliability(Engine *e) diff --git a/src/error_gui.cpp b/src/error_gui.cpp --- a/src/error_gui.cpp +++ b/src/error_gui.cpp @@ -425,7 +425,7 @@ void ShowErrorMessage(StringID summary_m /** * Schedule a list of errors. * Note: This does not try to display the error now. This is useful if the window system is not yet running. - * @param data Error message datas; cleared afterwards + * @param datas Error message datas; cleared afterwards */ void ScheduleErrorMessage(ErrorList &datas) { diff --git a/src/fileio.cpp b/src/fileio.cpp --- a/src/fileio.cpp +++ b/src/fileio.cpp @@ -347,7 +347,7 @@ char *FioGetFullPath(char *buf, const ch /** * Find a path to the filename in one of the search directories. - * @param buf [out] Destination buffer for the path. + * @param[out] buf Destination buffer for the path. * @param last End of the destination buffer. * @param subdir Subdirectory to try. * @param filename Filename to look for. @@ -438,7 +438,7 @@ static FILE *FioFOpenFileSp(const char * /** * Opens a file from inside a tar archive. * @param entry The entry to open. - * @param filesize [out] If not \c NULL, size of the opened file. + * @param[out] filesize If not \c NULL, size of the opened file. * @return File handle of the opened file, or \c NULL if the file is not available. * @note The file is read from within the tar file, and may not return \c EOF after reading the whole file. */ @@ -460,7 +460,6 @@ FILE *FioFOpenFileTar(TarFileListEntry * * Opens a OpenTTD file somewhere in a personal or global directory. * @param filename Name of the file to open. * @param subdir Subdirectory to open. - * @param filename Name of the file to open. * @return File handle of the opened file, or \c NULL if the file is not available. */ FILE *FioFOpenFile(const char *filename, const char *mode, Subdirectory subdir, size_t *filesize) @@ -632,7 +631,7 @@ static void SimplifyFileName(char *name) /** * Perform the scanning of a particular subdirectory. - * @param subdir The subdirectory to scan. + * @param sd The subdirectory to scan. * @return The number of found tar files. */ uint TarScanner::DoScan(Subdirectory sd) @@ -1303,7 +1302,7 @@ void SanitizeFilename(char *filename) /** * Load a file into memory. * @param filename Name of the file to load. - * @param lenp [out] Length of loaded data. + * @param[out] lenp Length of loaded data. * @param maxsize Maximum size to load. * @return Pointer to new memory containing the loaded data, or \c NULL if loading failed. * @note If \a maxsize less than the length of the file, loading fails. diff --git a/src/fios_gui.cpp b/src/fios_gui.cpp --- a/src/fios_gui.cpp +++ b/src/fios_gui.cpp @@ -201,7 +201,7 @@ static const TextColour _fios_colours[] /** * Sort the collected list save games prior to displaying it in the save/load gui. - * @param [inout] file_list List of save game files found in the directory. + * @param[in,out] file_list List of save game files found in the directory. */ static void SortSaveGameList(FileList &file_list) { diff --git a/src/game/game_text.cpp b/src/game/game_text.cpp --- a/src/game/game_text.cpp +++ b/src/game/game_text.cpp @@ -142,7 +142,7 @@ struct StringListReader : StringReader { /** * Create the reader. * @param data The data to fill during reading. - * @param file The file we are reading. + * @param strings The language strings we are reading. * @param master Are we reading the master file? * @param translation Are we reading a translation? */ diff --git a/src/gamelog.cpp b/src/gamelog.cpp --- a/src/gamelog.cpp +++ b/src/gamelog.cpp @@ -771,9 +771,9 @@ void GamelogGRFUpdate(const GRFConfig *o * Get some basic information from the given gamelog. * @param gamelog_action Pointer to the gamelog to extract information from. * @param gamelog_actions Number of actions in the given gamelog. - * @param [out] last_ottd_rev OpenTTD NewGRF version from the binary that saved the savegame last. - * @param [out] ever_modified Max value of 'modified' from all binaries that ever saved this savegame. - * @param [out] removed_newgrfs Set to true if any NewGRFs have been removed. + * @param[out] last_ottd_rev OpenTTD NewGRF version from the binary that saved the savegame last. + * @param[out] ever_modified Max value of 'modified' from all binaries that ever saved this savegame. + * @param[out] removed_newgrfs Set to true if any NewGRFs have been removed. */ void GamelogInfo(LoggedAction *gamelog_action, uint gamelog_actions, uint32 *last_ottd_rev, byte *ever_modified, bool *removed_newgrfs) { diff --git a/src/gfx.cpp b/src/gfx.cpp --- a/src/gfx.cpp +++ b/src/gfx.cpp @@ -703,8 +703,8 @@ Dimension GetStringBoundingBox(const cha } /** - * Get bounding box of a string. Uses parameters set by #DParam if needed. - * Has the same restrictions as #GetStringBoundingBox(const char *str). + * Get bounding box of a string. Uses parameters set by #SetDParam if needed. + * Has the same restrictions as #GetStringBoundingBox(const char *str, FontSize start_fontsize). * @param strid String to examine. * @return Width and height of the bounding box for the string in pixels. */ @@ -761,7 +761,7 @@ void DrawCharCentered(WChar c, int x, in /** * Get the size of a sprite. * @param sprid Sprite to examine. - * @param [out] offset Optionally returns the sprite position offset. + * @param[out] offset Optionally returns the sprite position offset. * @return Sprite size in pixels. * @note The size assumes (0, 0) as top-left coordinate and ignores any part of the sprite drawn at the left or above that position. */ @@ -1170,8 +1170,8 @@ byte GetDigitWidth(FontSize size) /** * Determine the broadest digits for guessing the maximum width of a n-digit number. - * @param [out] front Broadest digit, which is not 0. (Use this digit as first digit for numbers with more than one digit.) - * @param [out] next Broadest digit, including 0. (Use this digit for all digits, except the first one; or for numbers with only one digit.) + * @param[out] front Broadest digit, which is not 0. (Use this digit as first digit for numbers with more than one digit.) + * @param[out] next Broadest digit, including 0. (Use this digit for all digits, except the first one; or for numbers with only one digit.) * @param size Font of the digit */ void GetBroadestDigit(uint *front, uint *next, FontSize size) @@ -1635,8 +1635,8 @@ void SetAnimatedMouseCursor(const AnimCu * Update cursor position on mouse movement. * @param x New X position. * @param y New Y position. - * @param queued True, if the OS queues mouse warps after pending mouse movement events. - * False, if the warp applies instantaneous. + * @param queued_warp True, if the OS queues mouse warps after pending mouse movement events. + * False, if the warp applies instantaneous. * @return true, if the OS cursor position should be warped back to this->pos. */ bool CursorVars::UpdateCursorPosition(int x, int y, bool queued_warp) diff --git a/src/gfx_type.h b/src/gfx_type.h --- a/src/gfx_type.h +++ b/src/gfx_type.h @@ -189,7 +189,7 @@ union Colour { /** * Create a new colour. - * @param The colour in the correct packed format. + * @param data The colour in the correct packed format. */ Colour(uint data = 0) : data(data) { diff --git a/src/gfxinit.cpp b/src/gfxinit.cpp --- a/src/gfxinit.cpp +++ b/src/gfxinit.cpp @@ -80,7 +80,7 @@ static uint LoadGrfFile(const char *file /** * Load an old fashioned GRF file to replace already loaded sprites. * @param filename The name of the file to open. - * @param index_tlb The offsets of each of the sprites. + * @param index_tbl The offsets of each of the sprites. * @param file_index The Fio offset to load the file in. * @return The number of loaded sprites. */ diff --git a/src/goal_gui.cpp b/src/goal_gui.cpp --- a/src/goal_gui.cpp +++ b/src/goal_gui.cpp @@ -101,7 +101,7 @@ struct GoalListWindow : public Window { /** * Handle clicking at a goal. - * @param s @Goal clicked at. + * @param s #Goal clicked at. */ void HandleClick(const Goal *s) { @@ -193,7 +193,7 @@ struct GoalListWindow : public Window { /** * Draws either the global goals or the company goal section. * This is a helper method for #DrawWidget. - * @param pos [inout] Vertical line number to draw. + * @param[in,out] pos Vertical line number to draw. * @param cap Number of lines to draw in the window. * @param x Left edge of the text line to draw. * @param y Vertical position of the top edge of the window. @@ -250,8 +250,8 @@ struct GoalListWindow : public Window { /** * Draws a given column of the goal list. * @param column Which column to draw. - * @wid Pointer to the goal list widget. - * @progress_col_width Width of the progress column. + * @param wid Pointer to the goal list widget. + * @param progress_col_width Width of the progress column. * @return max width of drawn text */ void DrawListColumn(GoalColumn column, NWidgetBase *wid, uint progress_col_width) const diff --git a/src/group_cmd.cpp b/src/group_cmd.cpp --- a/src/group_cmd.cpp +++ b/src/group_cmd.cpp @@ -98,7 +98,7 @@ void GroupStatistics::Clear() } /** - * Update all caches after loading a game, changing NewGRF etc.. + * Update all caches after loading a game, changing NewGRF, etc. */ /* static */ void GroupStatistics::UpdateAfterLoad() { diff --git a/src/group_gui.cpp b/src/group_gui.cpp --- a/src/group_gui.cpp +++ b/src/group_gui.cpp @@ -977,11 +977,11 @@ static inline VehicleGroupWindow *FindVe } /** - * Opens a 'Rename group' window for newly created group - * @param success did command succeed? - * @param tile unused - * @param p1 vehicle type - * @param p2 unused + * Opens a 'Rename group' window for newly created group. + * @param result Did command succeed? + * @param tile Unused. + * @param p1 Vehicle type. + * @param p2 Unused. * @see CmdCreateGroup */ void CcCreateGroup(const CommandCost &result, TileIndex tile, uint32 p1, uint32 p2) @@ -995,7 +995,7 @@ void CcCreateGroup(const CommandCost &re /** * Open rename window after adding a vehicle to a new group via drag and drop. - * @param success Did command succeed? + * @param result Did command succeed? * @param tile Unused. * @param p1 Unused. * @param p2 Bit 0-19: Vehicle ID. diff --git a/src/heightmap.cpp b/src/heightmap.cpp --- a/src/heightmap.cpp +++ b/src/heightmap.cpp @@ -447,9 +447,9 @@ void FixSlopes() * Reads the heightmap with the correct file reader. * @param dft Type of image file. * @param filename Name of the file to load. - * @param [out] x Length of the image. - * @param [out] y Height of the image. - * @param [inout] map If not \c NULL, destination to store the loaded block of image data. + * @param[out] x Length of the image. + * @param[out] y Height of the image. + * @param[in,out] map If not \c NULL, destination to store the loaded block of image data. * @return Whether loading was successful. */ static bool ReadHeightMap(DetailedFileType dft, const char *filename, uint *x, uint *y, byte **map) diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp --- a/src/industry_cmd.cpp +++ b/src/industry_cmd.cpp @@ -1323,7 +1323,7 @@ static CheckNewIndustryProc * const _che * Find a town for the industry, while checking for multiple industries in the same town. * @param tile Position of the industry to build. * @param type Industry type. - * @param [out] town Pointer to return town for the new industry, \c NULL is written if no good town can be found. + * @param[out] t Pointer to return town for the new industry, \c NULL is written if no good town can be found. * @return Succeeded or failed command. * * @pre \c *t != NULL @@ -1365,14 +1365,14 @@ bool IsSlopeRefused(Slope current, Slope /** * Are the tiles of the industry free? - * @param tile Position to check. - * @param it Industry tiles table. - * @param itspec_index The index of the itsepc to build/fund - * @param type Type of the industry. - * @param initial_random_bits The random bits the industry is going to have after construction. - * @param founder Industry founder - * @param creation_type The circumstances the industry is created under. - * @param [out] custom_shape_check Perform custom check for the site. + * @param tile Position to check. + * @param it Industry tiles table. + * @param itspec_index The index of the itsepc to build/fund + * @param type Type of the industry. + * @param initial_random_bits The random bits the industry is going to have after construction. + * @param founder Industry founder + * @param creation_type The circumstances the industry is created under. + * @param[out] custom_shape_check Perform custom check for the site. * @return Failed or succeeded command. */ static CommandCost CheckIfIndustryTilesAreFree(TileIndex tile, const IndustryTileTable *it, uint itspec_index, int type, uint16 initial_random_bits, Owner founder, IndustryAvailabilityCallType creation_type, bool *custom_shape_check = NULL) @@ -1793,11 +1793,11 @@ static void DoCreateNewIndustry(Industry * @param flags of operations to conduct * @param indspec pointer to industry specifications * @param itspec_index the index of the itsepc to build/fund - * @param seed random seed (possibly) used by industries - * @param initial_random_bits The random bits the industry is going to have after construction. + * @param random_var8f random seed (possibly) used by industries + * @param random_initial_bits The random bits the industry is going to have after construction. * @param founder Founder of the industry * @param creation_type The circumstances the industry is created under. - * @param [out] ip Pointer to store newly created industry. + * @param[out] ip Pointer to store newly created industry. * @return Succeeded or failed command. * * @post \c *ip contains the newly created industry if all checks are successful and the \a flags request actual creation, else it contains \c NULL afterwards. @@ -1961,7 +1961,7 @@ static Industry *CreateNewIndustry(TileI /** * Compute the appearance probability for an industry during map creation. * @param it Industry type to compute. - * @param [out] force_at_least_one Returns whether at least one instance should be forced on map creation. + * @param[out] force_at_least_one Returns whether at least one instance should be forced on map creation. * @return Relative probability for the industry to appear. */ static uint32 GetScaledIndustryGenerationProbability(IndustryType it, bool *force_at_least_one) @@ -1986,7 +1986,7 @@ static uint32 GetScaledIndustryGeneratio /** * Compute the probability for constructing a new industry during game play. * @param it Industry type to compute. - * @param [out] min_number Minimal number of industries that should exist at the map. + * @param[out] min_number Minimal number of industries that should exist at the map. * @return Relative probability for the industry to appear. */ static uint16 GetIndustryGamePlayProbability(IndustryType it, byte *min_number) diff --git a/src/industry_gui.cpp b/src/industry_gui.cpp --- a/src/industry_gui.cpp +++ b/src/industry_gui.cpp @@ -1580,7 +1580,7 @@ struct CargoesField { /** * Connect a cargo from an industry to the #CFT_CARGO column. * @param cargo Cargo to connect. - * @param produced Cargo is produced (if \c false, cargo is assumed to be accepted). + * @param producer Cargo is produced (if \c false, cargo is assumed to be accepted). * @return Horizontal connection index, or \c -1 if not accepted at all. */ int ConnectCargo(CargoID cargo, bool producer) @@ -1697,7 +1697,7 @@ struct CargoesField { /** * Draw the field. * @param xpos Position of the left edge. - * @param vpos Position of the top edge. + * @param ypos Position of the top edge. */ void Draw(int xpos, int ypos) const { diff --git a/src/ini_type.h b/src/ini_type.h --- a/src/ini_type.h +++ b/src/ini_type.h @@ -70,7 +70,7 @@ struct IniLoadFile { * Open the INI file. * @param filename Name of the INI file. * @param subdir The subdir to load the file from. - * @param size [out] Size of the opened file. + * @param[out] size Size of the opened file. * @return File handle of the opened file, or \c NULL. */ virtual FILE *OpenFile(const char *filename, Subdirectory subdir, size_t *size) = 0; diff --git a/src/linkgraph/demands.cpp b/src/linkgraph/demands.cpp --- a/src/linkgraph/demands.cpp +++ b/src/linkgraph/demands.cpp @@ -115,7 +115,6 @@ public: * Check if there is any acceptance left for this node. In asymmetric distribution * nodes always accept as long as their demand > 0. * @param to The node to be checked. - * @param to_anno Unused. */ inline bool HasDemandLeft(const Node &to) { return to.Demand() > 0; } }; diff --git a/src/linkgraph/demands.h b/src/linkgraph/demands.h --- a/src/linkgraph/demands.h +++ b/src/linkgraph/demands.h @@ -30,7 +30,7 @@ public: /** * Call the demand calculator on the given component. - * @param graph Component to calculate the demands for. + * @param job Component to calculate the demands for. */ virtual void Run(LinkGraphJob &job) const { DemandCalculator c(job); } diff --git a/src/linkgraph/flowmapper.cpp b/src/linkgraph/flowmapper.cpp --- a/src/linkgraph/flowmapper.cpp +++ b/src/linkgraph/flowmapper.cpp @@ -16,7 +16,7 @@ /** * Map the paths generated by the MCF solver into flows associated with nodes. - * @param component the link graph component to be used. + * @param job the link graph component to be used. */ void FlowMapper::Run(LinkGraphJob &job) const { diff --git a/src/linkgraph/linkgraph.cpp b/src/linkgraph/linkgraph.cpp --- a/src/linkgraph/linkgraph.cpp +++ b/src/linkgraph/linkgraph.cpp @@ -252,8 +252,6 @@ void LinkGraph::Node::RemoveEdge(NodeID * least the given capacity and usage, otherwise add the capacity and usage. * In any case set the respective update timestamp(s), according to the given * mode. - * @param from Start node of the edge. - * @param to End node of the edge. * @param capacity Capacity to be added/updated. * @param usage Usage to be added. * @param mode Update mode to be applied. diff --git a/src/linkgraph/linkgraph_gui.cpp b/src/linkgraph/linkgraph_gui.cpp --- a/src/linkgraph/linkgraph_gui.cpp +++ b/src/linkgraph/linkgraph_gui.cpp @@ -425,7 +425,7 @@ LinkGraphLegendWindow::LinkGraphLegendWi /** * Set the overlay belonging to this menu and import its company/cargo settings. - * @params overlay New overlay for this menu. + * @param overlay New overlay for this menu. */ void LinkGraphLegendWindow::SetOverlay(LinkGraphOverlay *overlay) { this->overlay = overlay; diff --git a/src/linkgraph/mcf.cpp b/src/linkgraph/mcf.cpp --- a/src/linkgraph/mcf.cpp +++ b/src/linkgraph/mcf.cpp @@ -193,7 +193,7 @@ public: * Determines if an extension to the given Path with the given parameters is * better than this path. * @param base Other path. - * @param cap Capacity of the new edge to be added to base. + * @param free_cap Capacity of the new edge to be added to base. * @param dist Distance of the new edge. * @return True if base + the new edge would be better than the path associated * with this annotation. @@ -227,7 +227,7 @@ bool DistanceAnnotation::IsBetter(const * Determines if an extension to the given Path with the given parameters is * better than this path. * @param base Other path. - * @param cap Capacity of the new edge to be added to base. + * @param free_cap Capacity of the new edge to be added to base. * @param dist Distance of the new edge. * @return True if base + the new edge would be better than the path associated * with this annotation. diff --git a/src/map_type.h b/src/map_type.h --- a/src/map_type.h +++ b/src/map_type.h @@ -71,7 +71,7 @@ static const uint MAX_MAP_SIZE = 1 * Approximation of the length of a straight track, relative to a diagonal * track (ie the size of a tile side). * - * #defined instead of const so it can + * \#defined instead of const so it can * stay integer. (no runtime float operations) Is this needed? * Watch out! There are _no_ brackets around here, to prevent intermediate * rounding! Be careful when using this! diff --git a/src/misc/dbg_helpers.cpp b/src/misc/dbg_helpers.cpp --- a/src/misc/dbg_helpers.cpp +++ b/src/misc/dbg_helpers.cpp @@ -117,7 +117,7 @@ void DumpTarget::WriteIndent() } } -/** Write a line with indent at the beginning and at the end. */ +/** Write a line with indent at the beginning and \ at the end. */ void DumpTarget::WriteLine(const char *format, ...) { WriteIndent(); @@ -143,7 +143,7 @@ void DumpTarget::WriteTile(const char *n } /** - * Open new structure (one level deeper than the current one) 'name = {'. + * Open new structure (one level deeper than the current one) 'name = {\'. */ void DumpTarget::BeginStruct(size_t type_id, const char *name, const void *ptr) { @@ -167,7 +167,7 @@ void DumpTarget::BeginStruct(size_t type } /** - * Close structure '}'. + * Close structure '}\'. */ void DumpTarget::EndStruct() { diff --git a/src/misc/getoptdata.h b/src/misc/getoptdata.h --- a/src/misc/getoptdata.h +++ b/src/misc/getoptdata.h @@ -34,7 +34,7 @@ struct GetOptData { int numleft; ///< Number of arguments left in #argv. char **argv; ///< Remaining command line arguments. const OptionData *options; ///< Command line option descriptions. - char *cont; ///< Next call to #MyGetOpt should start here (in the middle of an argument). + char *cont; ///< Next call to #GetOpt should start here (in the middle of an argument). /** * Constructor of the data store. diff --git a/src/misc_gui.cpp b/src/misc_gui.cpp --- a/src/misc_gui.cpp +++ b/src/misc_gui.cpp @@ -732,7 +732,7 @@ struct TooltipsWindow : public Window * @param str String to be displayed * @param paramcount number of params to deal with * @param params (optional) up to 5 pieces of additional information that may be added to a tooltip - * @param use_left_mouse_button close the tooltip when the left (true) or right (false) mouse button is released + * @param close_tooltip when the left (true) or right (false) mouse button is released */ void GuiShowTooltips(Window *parent, StringID str, uint paramcount, const uint64 params[], TooltipCloseCondition close_tooltip) { @@ -1068,7 +1068,7 @@ void ShowQueryString(StringID str, Strin */ struct QueryWindow : public Window { QueryCallbackProc *proc; ///< callback function executed on closing of popup. Window* points to parent, bool is true if 'yes' clicked, false otherwise - uint64 params[10]; ///< local copy of _decode_parameters + uint64 params[10]; ///< local copy of #_global_string_params StringID message; ///< message shown for query window StringID caption; ///< title of window diff --git a/src/music/midifile.cpp b/src/music/midifile.cpp --- a/src/music/midifile.cpp +++ b/src/music/midifile.cpp @@ -520,8 +520,8 @@ struct MpsMachine { /** * Construct a TTD DOS music format decoder. - * @param songdata Buffer of song data from CAT file, ownership remains with caller - * @param songdatalen Length of the data buffer in bytes + * @param data Buffer of song data from CAT file, ownership remains with caller + * @param length Length of the data buffer in bytes * @param target MidiFile object to add decoded data to */ MpsMachine(const byte *data, size_t length, MidiFile &target) diff --git a/src/music/music_driver.hpp b/src/music/music_driver.hpp --- a/src/music/music_driver.hpp +++ b/src/music/music_driver.hpp @@ -21,7 +21,7 @@ class MusicDriver : public Driver { public: /** * Play a particular song. - * @param filename The name of file with the song to play. + * @param song The information for the song to play. */ virtual void PlaySong(const MusicSongInfo &song) = 0; diff --git a/src/network/network_content_gui.cpp b/src/network/network_content_gui.cpp --- a/src/network/network_content_gui.cpp +++ b/src/network/network_content_gui.cpp @@ -519,7 +519,7 @@ public: * Create the content list window. * @param desc the window description to pass to Window's constructor. * @param select_all Whether the select all button is allowed or not. - * @param type the main type of content to display or #CONTENT_TYPE_END. + * @param types the main type of content to display or #CONTENT_TYPE_END. * When a type other than #CONTENT_TYPE_END is given, dependencies of * other types are only shown when content that depend on them are * selected. diff --git a/src/network/network_server.cpp b/src/network/network_server.cpp --- a/src/network/network_server.cpp +++ b/src/network/network_server.cpp @@ -2137,7 +2137,7 @@ bool NetworkCompanyHasClients(CompanyID /** - * Get the name of the client, if the user did not send it yet, Client # is used. + * Get the name of the client, if the user did not send it yet, Client ID is used. * @param client_name The variable to write the name to. * @param last The pointer to the last element of the destination buffer */ diff --git a/src/newgrf.cpp b/src/newgrf.cpp --- a/src/newgrf.cpp +++ b/src/newgrf.cpp @@ -194,7 +194,7 @@ static GrfProcessingState _cur; /** * Helper to check whether an image index is valid for a particular NewGRF vehicle. - * @param The type of vehicle. + * @tparam T The type of vehicle. * @param image_index The image index to check. * @return True iff the image index is valid, or 0xFD (use new graphics). */ @@ -734,9 +734,9 @@ static void MapSpriteMappingRecolour(Pal * @param invert_action1_flag Set to true, if palette bit 15 means 'not from action 1'. * @param use_cur_spritesets Whether to use currently referenceable action 1 sets. * @param feature GrfSpecFeature to use spritesets from. - * @param [out] grf_sprite Read sprite and palette. - * @param [out] max_sprite_offset Optionally returns the number of sprites in the spriteset of the sprite. (0 if no spritset) - * @param [out] max_palette_offset Optionally returns the number of sprites in the spriteset of the palette. (0 if no spritset) + * @param[out] grf_sprite Read sprite and palette. + * @param[out] max_sprite_offset Optionally returns the number of sprites in the spriteset of the sprite. (0 if no spritset) + * @param[out] max_palette_offset Optionally returns the number of sprites in the spriteset of the palette. (0 if no spritset) * @return Read TileLayoutFlags. */ static TileLayoutFlags ReadSpriteLayoutSprite(ByteReader *buf, bool read_flags, bool invert_action1_flag, bool use_cur_spritesets, int feature, PalSpriteID *grf_sprite, uint16 *max_sprite_offset = NULL, uint16 *max_palette_offset = NULL) @@ -1845,7 +1845,7 @@ static ChangeInfoResult AircraftVehicleC /** * Define properties for stations - * @param stdid StationID of the first station tile. + * @param stid StationID of the first station tile. * @param numinfo Number of subsequent station tiles to change the property for. * @param prop The property to change. * @param buf The property value. @@ -2553,7 +2553,7 @@ static ChangeInfoResult TownHouseChangeI * @param gvid ID of the global variable. This is basically only checked for zerones. * @param numinfo Number of subsequent IDs to change the property for. * @param buf The property value. - * @param [in,out] translation_table Storage location for the translation table. + * @param[in,out] translation_table Storage location for the translation table. * @param name Name of the table for debug output. * @return ChangeInfoResult. */ diff --git a/src/newgrf_airport.cpp b/src/newgrf_airport.cpp --- a/src/newgrf_airport.cpp +++ b/src/newgrf_airport.cpp @@ -216,7 +216,6 @@ void AirportOverrideManager::SetEntitySp /** * Store a value into the object's persistent storage. - * @param object Object that we want to query. * @param pos Position in the persistent storage to use. * @param value Value to store. */ diff --git a/src/newgrf_animation_base.h b/src/newgrf_animation_base.h --- a/src/newgrf_animation_base.h +++ b/src/newgrf_animation_base.h @@ -31,7 +31,6 @@ template wires, GetStationGfx(tile)); } -/** Wrapper for animation control, see #GetStationCallback. */ +/** Wrapper for animation control, see GetStationCallback. */ uint16 GetAnimStationCallback(CallbackID callback, uint32 param1, uint32 param2, const StationSpec *statspec, BaseStation *st, TileIndex tile, int extra_data) { return GetStationCallback(callback, param1, param2, statspec, st, tile); diff --git a/src/newgrf_text.cpp b/src/newgrf_text.cpp --- a/src/newgrf_text.cpp +++ b/src/newgrf_text.cpp @@ -329,7 +329,7 @@ struct UnmappedChoiceList : ZeroedMemory * @param language_id The (NewGRF) language ID associated with this string. * @param allow_newlines Whether newlines are allowed in the string or not. * @param str The string to translate. - * @param [out] olen The length of the final string. + * @param[out] olen The length of the final string. * @param byte80 The control code to use as replacement for the 0x80-value. * @return The translated string. */ diff --git a/src/news_gui.cpp b/src/news_gui.cpp --- a/src/news_gui.cpp +++ b/src/news_gui.cpp @@ -494,7 +494,7 @@ struct NewsWindow : Window { private: /** - * Moves the window so #newtop is new 'top' coordinate. Makes screen dirty where needed. + * Moves the window to a new #top coordinate. Makes screen dirty where needed. * @param newtop new top coordinate */ void SetWindowTop(int newtop) @@ -962,7 +962,6 @@ void ShowLastNewsMessage() * @param y position of the string * @param colour the colour the string will be shown in * @param *ni NewsItem being printed - * @param maxw maximum width of string in pixels */ static void DrawNewsString(uint left, uint right, int y, TextColour colour, const NewsItem *ni) { diff --git a/src/object_gui.cpp b/src/object_gui.cpp --- a/src/object_gui.cpp +++ b/src/object_gui.cpp @@ -520,10 +520,7 @@ static WindowDesc _build_object_desc( _nested_build_object_widgets, lengthof(_nested_build_object_widgets) ); -/** - * Show our object picker. - * @param w The toolbar window we're associated with. - */ +/** Show our object picker. */ void ShowBuildObjectPicker() { /* Don't show the place object button when there are no objects to place. */ diff --git a/src/openttd.cpp b/src/openttd.cpp --- a/src/openttd.cpp +++ b/src/openttd.cpp @@ -989,9 +989,9 @@ static void MakeNewEditorWorld() * Load the specified savegame but on error do different things. * If loading fails due to corrupt savegame, bad version, etc. go back to * a previous correct state. In the menu for example load the intro game again. - * @param mode mode of loading, either SL_LOAD or SL_OLD_LOAD + * @param filename file to be loaded + * @param fop mode of loading, always SLO_LOAD * @param newgm switch to this mode of loading fails due to some unknown error - * @param filename file to be loaded * @param subdir default directory to look for filename, set to 0 if not needed * @param lf Load filter to use, if NULL: use filename + subdir. */ diff --git a/src/order_cmd.cpp b/src/order_cmd.cpp --- a/src/order_cmd.cpp +++ b/src/order_cmd.cpp @@ -1948,7 +1948,6 @@ void DeleteVehicleOrders(Vehicle *v, boo * Clamp the service interval to the correct min/max. The actual min/max values * depend on whether it's in percent or days. * @param interval proposed service interval - * @param company_id the owner of the vehicle * @return Clamped service interval */ uint16 GetServiceIntervalClamped(uint interval, bool ispercent) diff --git a/src/os/windows/win32.cpp b/src/os/windows/win32.cpp --- a/src/os/windows/win32.cpp +++ b/src/os/windows/win32.cpp @@ -625,11 +625,11 @@ char *convert_from_fs(const TCHAR *name, * Convert from OpenTTD's encoding to that of the environment in * UNICODE. OpenTTD encoding is UTF8, local is wide * @param name pointer to a valid string that will be converted - * @param utf16_buf pointer to a valid wide-char buffer that will receive the + * @param system_buf pointer to a valid wide-char buffer that will receive the * converted string * @param buflen length in wide characters of the receiving buffer * @param console_cp convert to the console encoding instead of the normal system encoding. - * @return pointer to utf16_buf. If conversion fails the string is of zero-length + * @return pointer to system_buf. If conversion fails the string is of zero-length */ TCHAR *convert_to_fs(const char *name, TCHAR *system_buf, size_t buflen, bool console_cp) { diff --git a/src/osk_gui.cpp b/src/osk_gui.cpp --- a/src/osk_gui.cpp +++ b/src/osk_gui.cpp @@ -437,9 +437,9 @@ void UpdateOSKOriginalText(const Window /** * Check whether the OSK is opened for a specific editbox. - * @parent w Window to check for + * @param w Window to check for * @param button Editbox of \a w to check for - * @return true if the OSK is oppened for \a button. + * @return true if the OSK is opened for \a button. */ bool IsOSKOpenedFor(const Window *w, int button) { diff --git a/src/pathfinder/npf/aystar.cpp b/src/pathfinder/npf/aystar.cpp --- a/src/pathfinder/npf/aystar.cpp +++ b/src/pathfinder/npf/aystar.cpp @@ -156,7 +156,7 @@ void AyStar::CheckTile(AyStarNode *curre * his neighbour items. If they are valid, they are added to be checked too. * @return Possible values: * - #AYSTAR_EMPTY_OPENLIST : indicates all items are tested, and no path has been found. - * - #AYSTAR_LIMIT_REACHED : Indicates that the max_nodes limit has been reached. + * - #AYSTAR_LIMIT_REACHED : Indicates that the max_search_nodes limit has been reached. * - #AYSTAR_FOUND_END_NODE : indicates we found the end. Path_found now is true, and in path is the path found. * - #AYSTAR_STILL_BUSY : indicates we have done this tile, did not found the path yet, and have items left to try. */ diff --git a/src/pathfinder/npf/aystar.h b/src/pathfinder/npf/aystar.h --- a/src/pathfinder/npf/aystar.h +++ b/src/pathfinder/npf/aystar.h @@ -30,7 +30,7 @@ enum AystarStatus { AYSTAR_EMPTY_OPENLIST, ///< All items are tested, and no path has been found. AYSTAR_STILL_BUSY, ///< Some checking was done, but no path found yet, and there are still items left to try. AYSTAR_NO_PATH, ///< No path to the goal was found. - AYSTAR_LIMIT_REACHED, ///< The #max_nodes limit has been reached, aborting search. + AYSTAR_LIMIT_REACHED, ///< The #AyStar::max_search_nodes limit has been reached, aborting search. AYSTAR_DONE, ///< Not an end-tile, or wrong direction. }; @@ -93,9 +93,9 @@ typedef int32 AyStar_CalculateG(AyStar * typedef int32 AyStar_CalculateH(AyStar *aystar, AyStarNode *current, OpenListNode *parent); /** - * This function requests the tiles around the current tile and put them in #tiles_around. - * #tiles_around is never reset, so if you are not using directions, just leave it alone. - * \warning Never add more tiles_around than memory allocated for it. + * This function requests the tiles around the current tile and put them in #neighbours. + * #neighbours is never reset, so if you are not using directions, just leave it alone. + * @warning Never add more #neighbours than memory allocated for it. */ typedef void AyStar_GetNeighbours(AyStar *aystar, OpenListNode *current); diff --git a/src/pathfinder/yapf/nodelist.hpp b/src/pathfinder/yapf/nodelist.hpp --- a/src/pathfinder/yapf/nodelist.hpp +++ b/src/pathfinder/yapf/nodelist.hpp @@ -25,7 +25,7 @@ template CItemArray; ///< Type that we will use as item container. typedef CHashTableT COpenList; ///< How pointers to open nodes will be stored. typedef CHashTableT CClosedList; ///< How pointers to closed nodes will be stored. diff --git a/src/rail.cpp b/src/rail.cpp --- a/src/rail.cpp +++ b/src/rail.cpp @@ -251,7 +251,7 @@ RailTypes AddDateIntroducedRailTypes(Rai /** * Get the rail types the given company can build. - * @param c the company to get the rail types for. + * @param company the company to get the rail types for. * @return the rail types. */ RailTypes GetCompanyRailtypes(CompanyID company) diff --git a/src/rail.h b/src/rail.h --- a/src/rail.h +++ b/src/rail.h @@ -239,7 +239,7 @@ public: * When #INVALID_DATE or a vehicle using this railtype gets introduced earlier, * the vehicle's introduction date will be used instead for this railtype. * The introduction at this date is furthermore limited by the - * #introduction_required_types. + * #introduction_required_railtypes. */ Date introduction_date; diff --git a/src/road_func.h b/src/road_func.h --- a/src/road_func.h +++ b/src/road_func.h @@ -39,7 +39,7 @@ static inline bool IsValidRoadType(RoadT /** * Whether the given roadtype is valid. - * @param rt the roadtype to check for validness + * @param r the roadtype to check for validness * @return true if and only if valid */ static inline bool IsValidRoadBits(RoadBits r) diff --git a/src/roadveh_cmd.cpp b/src/roadveh_cmd.cpp --- a/src/roadveh_cmd.cpp +++ b/src/roadveh_cmd.cpp @@ -255,7 +255,7 @@ void RoadVehUpdateCache(RoadVehicle *v, * @param flags type of operation. * @param e the engine to build. * @param data unused. - * @param ret[out] the vehicle that has been built. + * @param[out] ret the vehicle that has been built. * @return the cost of this operation or an error. */ CommandCost CmdBuildRoadVehicle(TileIndex tile, DoCommandFlag flags, const Engine *e, uint16 data, Vehicle **ret) diff --git a/src/saveload/linkgraph_sl.cpp b/src/saveload/linkgraph_sl.cpp --- a/src/saveload/linkgraph_sl.cpp +++ b/src/saveload/linkgraph_sl.cpp @@ -132,7 +132,7 @@ static const SaveLoad _edge_desc[] = { /** * Save/load a link graph. - * @param comp Link graph to be saved or loaded. + * @param lg Link graph to be saved or loaded. */ void SaveLoad_LinkGraph(LinkGraph &lg) { diff --git a/src/saveload/saveload.cpp b/src/saveload/saveload.cpp --- a/src/saveload/saveload.cpp +++ b/src/saveload/saveload.cpp @@ -2786,7 +2786,7 @@ SaveOrLoadResult LoadWithFilter(LoadFilt * Main Save or Load function where the high-level saveload functions are * 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 mode. Load can also be a TTD(Patch) game. Use #SL_LOAD, #SL_OLD_LOAD, #SL_LOAD_CHECK, or #SL_SAVE. + * @param fop Save or load mode. Load can also be a TTD(Patch) game. * @param sb The sub directory to save the savegame in * @param threaded True when threaded saving is allowed * @return Return the result of the action. #SL_OK, #SL_ERROR, or #SL_REINIT ("unload" the game) diff --git a/src/saveload/saveload.h b/src/saveload/saveload.h --- a/src/saveload/saveload.h +++ b/src/saveload/saveload.h @@ -488,7 +488,7 @@ static inline bool SlIsObjectCurrentlyVa * Get the NumberType of a setting. This describes the integer type * as it is represented in memory * @param type VarType holding information about the variable-type - * @return return the SLE_VAR_* part of a variable-type description + * @return the SLE_VAR_* part of a variable-type description */ static inline VarType GetVarMemType(VarType type) { @@ -496,10 +496,10 @@ static inline VarType GetVarMemType(VarT } /** - * Get the #FileType of a setting. This describes the integer type + * Get the FileType of a setting. This describes the integer type * as it is represented in a savegame/file * @param type VarType holding information about the file-type - * @param return the SLE_FILE_* part of a variable-type description + * @return the SLE_FILE_* part of a variable-type description */ static inline VarType GetVarFileType(VarType type) { diff --git a/src/screenshot.cpp b/src/screenshot.cpp --- a/src/screenshot.cpp +++ b/src/screenshot.cpp @@ -708,7 +708,7 @@ static bool MakeSmallScreenshot(bool cra /** * Configure a ViewPort for rendering (a part of) the map into a screenshot. * @param t Screenshot type - * @param [out] vp Result viewport + * @param[out] vp Result viewport */ void SetupScreenshotViewport(ScreenshotType t, ViewPort *vp) { @@ -764,7 +764,7 @@ static bool MakeLargeWorldScreenshot(Scr /** * Callback for generating a heightmap. Supports 8bpp grayscale only. * @param userdata Pointer to user data. - * @param buf Destination buffer. + * @param buffer Destination buffer. * @param y Line number of the first line to write. * @param pitch Number of pixels to write (1 byte for 8bpp, 4 bytes for 32bpp). @see Colour * @param n Number of lines to write. diff --git a/src/settings.cpp b/src/settings.cpp --- a/src/settings.cpp +++ b/src/settings.cpp @@ -1459,7 +1459,7 @@ static int DecodeHexNibble(char c) * Parse a sequence of characters (supposedly hex digits) into a sequence of bytes. * After the hex number should be a \c '|' character. * @param pos First character to convert. - * @param dest [out] Output byte array to write the bytes. + * @param[out] dest Output byte array to write the bytes. * @param dest_size Number of bytes in \a dest. * @return Whether reading was successful. */ @@ -1748,7 +1748,7 @@ void SaveToConfig() /** * Get the list of known NewGrf presets. - * @param list[inout] Pointer to list for storing the preset names. + * @param[in,out] list Pointer to list for storing the preset names. */ void GetGRFPresetList(GRFPresetList *list) { diff --git a/src/settings_type.h b/src/settings_type.h --- a/src/settings_type.h +++ b/src/settings_type.h @@ -99,7 +99,7 @@ struct GUISettings { bool smooth_scroll; ///< smooth scroll viewports bool measure_tooltip; ///< show a permanent tooltip when dragging tools byte liveries; ///< options for displaying company liveries, 0=none, 1=self, 2=all - bool prefer_teamchat; ///< choose the chat message target with , true=all clients, false=your team + bool prefer_teamchat; ///< choose the chat message target with \, true=all clients, false=your team uint8 advanced_vehicle_list; ///< use the "advanced" vehicle list uint8 loading_indicators; ///< show loading indicators uint8 default_rail_type; ///< the default rail type for the rail GUI diff --git a/src/settingsgen/settingsgen.cpp b/src/settingsgen/settingsgen.cpp --- a/src/settingsgen/settingsgen.cpp +++ b/src/settingsgen/settingsgen.cpp @@ -205,7 +205,6 @@ static const char *DEFAULTS_GROUP_NAME /** * Load the INI file. * @param filename Name of the file to load. - * @param subdir The subdirectory to load from. * @return Loaded INI data. */ static IniLoadFile *LoadIniFile(const char *filename) @@ -413,12 +412,12 @@ static const OptionData _opts[] = { * After loading, the [pre-amble] group is copied verbatim if it exists. * * For every group with a name that matches a template name the template is written. - * It starts with a optional '#if' line if an 'if' item exists in the group. The item - * value is used as condition. Similarly, '#ifdef' and '#ifndef' lines are also written. + * It starts with a optional \c \#if line if an 'if' item exists in the group. The item + * value is used as condition. Similarly, \c \#ifdef and \c \#ifndef lines are also written. * Below the macro processor directives, the value of the template is written * at a line with its variables replaced by item values of the group being written. * If the group has no item for the variable, the [defaults] group is tried as fall back. - * Finally, '#endif' lines are written to match the macro processor lines. + * Finally, \c \#endif lines are written to match the macro processor lines. * * Last but not least, the [post-amble] group is copied verbatim. * diff --git a/src/ship_cmd.cpp b/src/ship_cmd.cpp --- a/src/ship_cmd.cpp +++ b/src/ship_cmd.cpp @@ -654,7 +654,7 @@ bool Ship::Tick() * @param flags type of operation. * @param e the engine to build. * @param data unused. - * @param ret[out] the vehicle that has been built. + * @param[out] ret the vehicle that has been built. * @return the cost of this operation or an error. */ CommandCost CmdBuildShip(TileIndex tile, DoCommandFlag flags, const Engine *e, uint16 data, Vehicle **ret) diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp --- a/src/smallmap_gui.cpp +++ b/src/smallmap_gui.cpp @@ -416,7 +416,7 @@ static const byte _tiletype_importance[] /** * Return the colour a tile would be displayed with in the small map in mode "Contour". * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "Contour" */ static inline uint32 GetSmallMapContoursPixels(TileIndex tile, TileType t) @@ -429,7 +429,7 @@ static inline uint32 GetSmallMapContours * Return the colour a tile would be displayed with in the small map in mode "Vehicles". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "Vehicles" */ static inline uint32 GetSmallMapVehiclesPixels(TileIndex tile, TileType t) @@ -442,7 +442,7 @@ static inline uint32 GetSmallMapVehicles * Return the colour a tile would be displayed with in the small map in mode "Industries". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "Industries" */ static inline uint32 GetSmallMapIndustriesPixels(TileIndex tile, TileType t) @@ -455,7 +455,7 @@ static inline uint32 GetSmallMapIndustri * Return the colour a tile would be displayed with in the small map in mode "Routes". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "Routes" */ static inline uint32 GetSmallMapRoutesPixels(TileIndex tile, TileType t) @@ -488,7 +488,7 @@ static inline uint32 GetSmallMapRoutesPi * Return the colour a tile would be displayed with in the small map in mode "link stats". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "link stats" */ static inline uint32 GetSmallMapLinkStatsPixels(TileIndex tile, TileType t) @@ -511,7 +511,7 @@ static const uint32 _vegetation_clear_bi * Return the colour a tile would be displayed with in the smallmap in mode "Vegetation". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the smallmap in mode "Vegetation" */ static inline uint32 GetSmallMapVegetationPixels(TileIndex tile, TileType t) @@ -538,7 +538,7 @@ static inline uint32 GetSmallMapVegetati * Return the colour a tile would be displayed with in the small map in mode "Owner". * * @param tile The tile of which we would like to get the colour. - * @param t Effective tile type of the tile (see #GetTileColours). + * @param t Effective tile type of the tile (see #SmallMapWindow::GetTileColours). * @return The colour of tile in the small map in mode "Owner" */ static inline uint32 GetSmallMapOwnerPixels(TileIndex tile, TileType t) @@ -611,7 +611,7 @@ inline Point SmallMapWindow::RemapTile(i * that tile for a point in the smallmap. * @param px Horizontal coordinate of the pixel. * @param py Vertical coordinate of the pixel. - * @param sub[out] Pixel position at the tile (0..3). + * @param[out] sub Pixel position at the tile (0..3). * @param add_sub Add current #subscroll to the position. * @return Tile being displayed at the given position relative to #scroll_x and #scroll_y. * @note The #subscroll offset is already accounted for. @@ -641,11 +641,11 @@ inline Point SmallMapWindow::PixelToTile /** * Compute base parameters of the smallmap such that tile (\a tx, \a ty) starts at pixel (\a x, \a y). - * @param tx Tile x coordinate. - * @param ty Tile y coordinate. - * @param x Non-negative horizontal position in the display where the tile starts. - * @param y Non-negative vertical position in the display where the tile starts. - * @param sub [out] Value of #subscroll needed. + * @param tx Tile x coordinate. + * @param ty Tile y coordinate. + * @param x Non-negative horizontal position in the display where the tile starts. + * @param y Non-negative vertical position in the display where the tile starts. + * @param[out] sub Value of #subscroll needed. * @return #scroll_x, #scroll_y values. */ Point SmallMapWindow::ComputeScroll(int tx, int ty, int x, int y, int *sub) diff --git a/src/station_base.h b/src/station_base.h --- a/src/station_base.h +++ b/src/station_base.h @@ -516,7 +516,7 @@ private: public: /** * Construct the iterator. - * @param ta Area, i.e. begin point and width/height of to-be-iterated area. + * @param st Station the airport is part of. */ AirportTileIterator(const Station *st) : OrthogonalTileIterator(st->airport), st(st) { diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp --- a/src/station_cmd.cpp +++ b/src/station_cmd.cpp @@ -662,7 +662,7 @@ static void UpdateStationSignCoord(BaseS /** * Common part of building various station parts and possibly attaching them to an existing one. - * @param [in,out] st Station to attach to + * @param[in,out] st Station to attach to * @param flags Command flags * @param reuse Whether to try to reuse a deleted station (gray sign) if possible * @param area Area occupied by the new part @@ -2624,9 +2624,9 @@ const DrawTileSprites *GetStationTileLay * Check whether a sprite is a track sprite, which can be replaced by a non-track ground sprite and a rail overlay. * If the ground sprite is suitable, \a ground is replaced with the new non-track ground sprite, and \a overlay_offset * is set to the overlay to draw. - * @param ti Positional info for the tile to decide snowyness etc. May be NULL. - * @param [in,out] ground Groundsprite to draw. - * @param [out] overlay_offset Overlay to draw. + * @param ti Positional info for the tile to decide snowyness etc. May be NULL. + * @param[in,out] ground Groundsprite to draw. + * @param[out] overlay_offset Overlay to draw. * @return true if overlay can be drawn. */ bool SplitGroundSpriteForOverlay(const TileInfo *ti, SpriteID *ground, RailTrackOffset *overlay_offset) diff --git a/src/station_gui.cpp b/src/station_gui.cpp --- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -802,7 +802,6 @@ static const NWidgetPart _nested_station * @param left left most coordinate to draw on * @param right right most coordinate to draw on * @param y y coordinate - * @param width the width of the view */ static void DrawCargoIcons(CargoID i, uint waiting, int left, int right, int y) { diff --git a/src/strgen/strgen_base.cpp b/src/strgen/strgen_base.cpp --- a/src/strgen/strgen_base.cpp +++ b/src/strgen/strgen_base.cpp @@ -85,7 +85,7 @@ void LangString::FreeTranslation() /** * Create a new string data container. - * @param max_strings The maximum number of strings. + * @param tabs The maximum number of strings. */ StringData::StringData(size_t tabs) : tabs(tabs), max_strings(tabs * TAB_SIZE) { diff --git a/src/string_base.h b/src/string_base.h --- a/src/string_base.h +++ b/src/string_base.h @@ -41,9 +41,9 @@ public: /** * Change the current string cursor. - * @param p New cursor position. + * @param pos New cursor position. * @return Actual new cursor position at the next valid character boundary. - * @pre p has to be inside the current string. + * @pre pos has to be inside the current string. */ virtual size_t SetCurPosition(size_t pos) = 0; diff --git a/src/strings.cpp b/src/strings.cpp --- a/src/strings.cpp +++ b/src/strings.cpp @@ -56,7 +56,7 @@ icu::Collator *_current_collator = NULL; #endif /* WITH_ICU_SORT */ static uint64 _global_string_params_data[20]; ///< Global array of string parameters. To access, use #SetDParam. -static WChar _global_string_params_type[20]; ///< Type of parameters stored in #_decode_parameters +static WChar _global_string_params_type[20]; ///< Type of parameters stored in #_global_string_params StringParameters _global_string_params(_global_string_params_data, 20, _global_string_params_type); /** Reset the type array. */ @@ -760,11 +760,10 @@ uint ConvertDisplaySpeedToKmhishSpeed(ui } /** * Parse most format codes within a string and write the result to a buffer. - * @param buff The buffer to write the final string to. - * @param str The original string with format codes. - * @param args Pointer to extra arguments used by various string codes. - * @param case_index - * @param last Pointer to just past the end of the buff array. + * @param buff The buffer to write the final string to. + * @param str_arg The original string with format codes. + * @param args Pointer to extra arguments used by various string codes. + * @param last Pointer to just past the end of the buff array. * @param dry_run True when the argt array is not yet initialized. */ static char *FormatString(char *buff, const char *str_arg, StringParameters *args, const char *last, uint case_index, bool game_script, bool dry_run) @@ -2003,7 +2002,7 @@ const char *GetCurrentLanguageIsoCode() /** * Check whether there are glyphs missing in the current language. - * @param Pointer to an address for storing the text pointer. + * @param[out] str Pointer to an address for storing the text pointer. * @return If glyphs are missing, return \c true, else return \c false. * @post If \c true is returned and str is not NULL, *str points to a string that is found to contain at least one missing glyph. */ diff --git a/src/textbuf.cpp b/src/textbuf.cpp --- a/src/textbuf.cpp +++ b/src/textbuf.cpp @@ -367,7 +367,6 @@ bool Textbuf::MovePos(uint16 keycode) /** * Initialize the textbuffer by supplying it the buffer to write into * and the maximum length of this buffer - * @param buf the buffer that will be holding the data for input * @param max_bytes maximum size in bytes, including terminating '\0' * @param max_chars maximum size in chars, including terminating '\0' */ diff --git a/src/tile_map.cpp b/src/tile_map.cpp --- a/src/tile_map.cpp +++ b/src/tile_map.cpp @@ -70,11 +70,11 @@ uint TileHeightOutsideMap(int x, int y) /** * Get a tile's slope given the heigh of its four corners. - * @param hnorth The height at the northern corner in the same unit as TileHeight. - * @param hwest The height at the western corner in the same unit as TileHeight. - * @param heast The height at the eastern corner in the same unit as TileHeight. - * @param hsouth The height at the southern corner in the same unit as TileHeight. - * @param [out] h The lowest height of the four corners. + * @param hnorth The height at the northern corner in the same unit as TileHeight. + * @param hwest The height at the western corner in the same unit as TileHeight. + * @param heast The height at the eastern corner in the same unit as TileHeight. + * @param hsouth The height at the southern corner in the same unit as TileHeight. + * @param[out] h The lowest height of the four corners. * @return The slope. */ static Slope GetTileSlopeGivenHeight(int hnorth, int hwest, int heast, int hsouth, int *h) @@ -134,7 +134,8 @@ Slope GetTileSlope(TileIndex tile, int * /** * Return the slope of a given tile outside the map. * - * @param tile Tile outside the map to compute slope of. + * @param x X-coordinate of the tile outside to compute height of. + * @param y Y-coordinate of the tile outside to compute height of. * @param h If not \c NULL, pointer to storage of z height. * @return Slope of the tile outside map, except for the HALFTILE part. */ @@ -194,7 +195,8 @@ int GetTileZ(TileIndex tile) /** * Get bottom height of the tile outside map. * - * @param tile Tile outside the map to compute height of. + * @param x X-coordinate of the tile outside to compute height of. + * @param y Y-coordinate of the tile outside to compute height of. * @return Minimum height of the tile outside the map. */ int GetTilePixelZOutsideMap(int x, int y) @@ -229,7 +231,8 @@ int GetTileMaxZ(TileIndex t) * * @see Detailed description in header. * - * @param tile Tile outside to compute height of. + * @param x X-coordinate of the tile outside to compute height of. + * @param y Y-coordinate of the tile outside to compute height of. * @return Maximum height of the tile. */ int GetTileMaxPixelZOutsideMap(int x, int y) diff --git a/src/tile_map.h b/src/tile_map.h --- a/src/tile_map.h +++ b/src/tile_map.h @@ -293,7 +293,7 @@ int GetTilePixelZOutsideMap(int x, int y /** * Get top height of the tile - * @param t Tile to compute height of + * @param tile Tile to compute height of * @return Maximum height of the tile */ static inline int GetTileMaxPixelZ(TileIndex tile) diff --git a/src/tilematrix_type.hpp b/src/tilematrix_type.hpp --- a/src/tilematrix_type.hpp +++ b/src/tilematrix_type.hpp @@ -87,7 +87,7 @@ public: /** * Get the area of the matrix square that contains a specific tile. - * @param The tile to get the map area for. + * @param tile The tile to get the map area for. * @param extend Extend the area by this many squares on all sides. * @return Tile area containing the tile. */ diff --git a/src/timetable_gui.cpp b/src/timetable_gui.cpp --- a/src/timetable_gui.cpp +++ b/src/timetable_gui.cpp @@ -139,7 +139,7 @@ static void FillTimetableArrivalDepartur /** * Callback for when a time has been chosen to start the time table - * @param window the window related to the setting of the date + * @param w the window related to the setting of the date * @param date the actually chosen date */ static void ChangeTimetableStartCallback(const Window *w, Date date) diff --git a/src/town_cmd.cpp b/src/town_cmd.cpp --- a/src/town_cmd.cpp +++ b/src/town_cmd.cpp @@ -3145,7 +3145,7 @@ static void UpdateTownRating(Town *t) /** * Updates town grow counter after growth rate change. * Preserves relative house builting progress whenever it can. - * @param town The town to calculate grow counter for + * @param t The town to calculate grow counter for * @param prev_growth_rate Town growth rate before it changed (one that was used with grow counter to be updated) */ static void UpdateTownGrowCounter(Town *t, uint16 prev_growth_rate) @@ -3160,7 +3160,7 @@ static void UpdateTownGrowCounter(Town * /** * Calculates amount of active stations in the range of town (HZB_TOWN_EDGE). - * @param town The town to calculate stations for + * @param t The town to calculate stations for * @returns Amount of active stations */ static int CountActiveStations(Town *t) @@ -3180,7 +3180,7 @@ static int CountActiveStations(Town *t) /** * Calculates town growth rate in normal conditions (custom growth rate not set). * If town growth speed is set to None(0) returns the same rate as if it was Normal(2). - * @param town The town to calculate growth rate for + * @param t The town to calculate growth rate for * @returns Calculated growth rate */ static uint GetNormalGrowthRate(Town *t) @@ -3203,7 +3203,7 @@ static uint GetNormalGrowthRate(Town *t) /** * Updates town growth rate. - * @param town The town to update growth rate for + * @param t The town to update growth rate for */ static void UpdateTownGrowthRate(Town *t) { @@ -3216,7 +3216,7 @@ static void UpdateTownGrowthRate(Town *t /** * Updates town growth state (whether it is growing or not). - * @param town The town to update growth for + * @param t The town to update growth for */ static void UpdateTownGrowth(Town *t) { diff --git a/src/train_cmd.cpp b/src/train_cmd.cpp --- a/src/train_cmd.cpp +++ b/src/train_cmd.cpp @@ -581,7 +581,7 @@ void GetTrainSpriteSize(EngineID engine, * @param tile tile of the depot where rail-vehicle is built. * @param flags type of operation. * @param e the engine to build. - * @param ret[out] the vehicle that has been built. + * @param[out] ret the vehicle that has been built. * @return the cost of this operation or an error. */ static CommandCost CmdBuildRailWagon(TileIndex tile, DoCommandFlag flags, const Engine *e, Vehicle **ret) @@ -713,7 +713,7 @@ static void AddRearEngineToMultiheadedTr * @param flags type of operation. * @param e the engine to build. * @param data bit 0 prevents any free cars from being added to the train. - * @param ret[out] the vehicle that has been built. + * @param[out] ret the vehicle that has been built. * @return the cost of this operation or an error. */ CommandCost CmdBuildRailVehicle(TileIndex tile, DoCommandFlag flags, const Engine *e, uint16 data, Vehicle **ret) @@ -935,8 +935,8 @@ static void NormaliseSubtypes(Train *cha * @note All vehicles are/were 'heads' of their chains. * @param original_dst The original destination chain. * @param dst The destination chain after constructing the train. - * @param original_dst The original source chain. - * @param dst The source chain after constructing the train. + * @param original_src The original source chain. + * @param src The source chain after constructing the train. * @return possible error of this command. */ static CommandCost CheckNewTrain(Train *original_dst, Train *dst, Train *original_src, Train *src) @@ -1054,8 +1054,8 @@ static CommandCost CheckTrainAttachment( * @note All vehicles are/were 'heads' of their chains. * @param original_dst The original destination chain. * @param dst The destination chain after constructing the train. - * @param original_dst The original source chain. - * @param dst The source chain after constructing the train. + * @param original_src The original source chain. + * @param src The source chain after constructing the train. * @param check_limit Whether to check the vehicle limit. * @return possible error of this command. */ @@ -1511,8 +1511,8 @@ static void MarkTrainAsStuck(Train *v) * Swap the two up/down flags in two ways: * - Swap values of \a swap_flag1 and \a swap_flag2, and * - If going up previously (#GVF_GOINGUP_BIT set), the #GVF_GOINGDOWN_BIT is set, and vice versa. - * @param swap_flag1 [inout] First train flag. - * @param swap_flag2 [inout] Second train flag. + * @param[in,out] swap_flag1 First train flag. + * @param[in,out] swap_flag2 Second train flag. */ static void SwapTrainFlags(uint16 *swap_flag1, uint16 *swap_flag2) { @@ -2014,9 +2014,9 @@ static FindDepotData FindClosestTrainDep /** * Locate the closest depot for this consist, and return the information to the caller. - * @param location [out] If not \c NULL and a depot is found, store its location in the given address. - * @param destination [out] If not \c NULL and a depot is found, store its index in the given address. - * @param reverse [out] If not \c NULL and a depot is found, store reversal information in the given address. + * @param[out] location If not \c NULL and a depot is found, store its location in the given address. + * @param[out] destination If not \c NULL and a depot is found, store its index in the given address. + * @param[out] reverse If not \c NULL and a depot is found, store reversal information in the given address. * @return A depot has been found. */ bool Train::FindClosestDepot(TileIndex *location, DestinationID *destination, bool *reverse) @@ -2307,9 +2307,9 @@ static const byte _initial_tile_subcoord * @param tile The tile the train is about to enter * @param enterdir Diagonal direction the train is coming from * @param tracks Usable tracks on the new tile - * @param path_found [out] Whether a path has been found or not. + * @param[out] path_found Whether a path has been found or not. * @param do_track_reservation Path reservation is requested - * @param dest [out] State and destination of the requested path + * @param[out] dest State and destination of the requested path * @return The best track the train should follow */ static Track DoTrainPathfind(const Train *v, TileIndex tile, DiagDirection enterdir, TrackBits tracks, bool &path_found, bool do_track_reservation, PBSTileInfo *dest) @@ -2419,11 +2419,11 @@ static PBSTileInfo ExtendTrainReservatio * @param override_railtype Whether all physically compatible railtypes should be followed. * @return True if a path to a safe stopping tile could be reserved. */ -static bool TryReserveSafeTrack(const Train *v, TileIndex tile, Trackdir td, bool override_tailtype) +static bool TryReserveSafeTrack(const Train *v, TileIndex tile, Trackdir td, bool override_railtype) { switch (_settings_game.pf.pathfinder_for_trains) { - case VPF_NPF: return NPFTrainFindNearestSafeTile(v, tile, td, override_tailtype); - case VPF_YAPF: return YapfTrainFindNearestSafeTile(v, tile, td, override_tailtype); + case VPF_NPF: return NPFTrainFindNearestSafeTile(v, tile, td, override_railtype); + case VPF_YAPF: return YapfTrainFindNearestSafeTile(v, tile, td, override_railtype); default: NOT_REACHED(); } diff --git a/src/tunnelbridge_cmd.cpp b/src/tunnelbridge_cmd.cpp --- a/src/tunnelbridge_cmd.cpp +++ b/src/tunnelbridge_cmd.cpp @@ -204,6 +204,7 @@ static CommandCost CheckBridgeSlopeSouth * Is a bridge of the specified type and length available? * @param bridge_type Wanted type of bridge. * @param bridge_len Wanted length of the bridge. + * @param flags Type of operation. * @return A succeeded (the requested bridge is available) or failed (it cannot be built) command. */ CommandCost CheckBridgeAvailability(BridgeType bridge_type, uint bridge_len, DoCommandFlag flags) diff --git a/src/vehicle.cpp b/src/vehicle.cpp --- a/src/vehicle.cpp +++ b/src/vehicle.cpp @@ -95,7 +95,7 @@ INSTANTIATE_POOL_METHODS(Vehicle) /** * Determine shared bounds of all sprites. - * @param [out] bounds Shared bounds. + * @param[out] bounds Shared bounds. */ void VehicleSpriteSeq::GetBounds(Rect *bounds) const { @@ -2859,7 +2859,7 @@ const uint16 &Vehicle::GetGroundVehicleF /** * Calculates the set of vehicles that will be affected by a given selection. - * @param set [inout] Set of affected vehicles. + * @param[in,out] set Set of affected vehicles. * @param v First vehicle of the selection. * @param num_vehicles Number of vehicles in the selection (not counting articulated parts). * @pre \a set must be empty. diff --git a/src/vehicle_base.h b/src/vehicle_base.h --- a/src/vehicle_base.h +++ b/src/vehicle_base.h @@ -324,7 +324,7 @@ public: uint16 load_unload_ticks; ///< Ticks to wait before starting next cycle. GroupID group_id; ///< Index of group Pool array - byte subtype; ///< subtype (Filled with values from #EffectVehicles/#TrainSubTypes/#AircraftSubTypes) + byte subtype; ///< subtype (Filled with values from #AircraftSubType/#DisasterSubType/#EffectVehicleType/#GroundVehicleSubtypeFlags) NewGRFCache grf_cache; ///< Cache of often used calculated NewGRF values VehicleCache vcache; ///< Cache of often used vehicle values. @@ -437,7 +437,7 @@ public: /** * Gets the sprite to show for the given direction * @param direction the direction the vehicle is facing - * @param [out] result Vehicle sprite sequence. + * @param[out] result Vehicle sprite sequence. */ virtual void GetImage(Direction direction, EngineImageType image_type, VehicleSpriteSeq *result) const { result->Clear(); } diff --git a/src/vehicle_cmd.cpp b/src/vehicle_cmd.cpp --- a/src/vehicle_cmd.cpp +++ b/src/vehicle_cmd.cpp @@ -206,7 +206,7 @@ CommandCost CmdSellVehicle(TileIndex til * @param engine_type Which engine to refit * @param new_cid Cargo type we are refitting to. * @param new_subtype New cargo subtype. - * @param [out] auto_refit_allowed The refit is allowed as an auto-refit. + * @param[out] auto_refit_allowed The refit is allowed as an auto-refit. * @return Price for refitting */ static int GetRefitCostFactor(const Vehicle *v, EngineID engine_type, CargoID new_cid, byte new_subtype, bool *auto_refit_allowed) @@ -238,7 +238,7 @@ static int GetRefitCostFactor(const Vehi * @param engine_type Which engine to refit * @param new_cid Cargo type we are refitting to. * @param new_subtype New cargo subtype. - * @param [out] auto_refit_allowed The refit is allowed as an auto-refit. + * @param[out] auto_refit_allowed The refit is allowed as an auto-refit. * @return Price for refitting */ static CommandCost GetRefitCost(const Vehicle *v, EngineID engine_type, CargoID new_cid, byte new_subtype, bool *auto_refit_allowed) diff --git a/src/vehicle_func.h b/src/vehicle_func.h --- a/src/vehicle_func.h +++ b/src/vehicle_func.h @@ -31,7 +31,7 @@ static const Money VEHICLE_PROFIT_THRESH /** * Helper to check whether an image index is valid for a particular vehicle. - * @param The type of vehicle. + * @tparam T The type of vehicle. * @param image_index The image index to check. * @return True iff the image index is valid. */ diff --git a/src/vehicle_gui.cpp b/src/vehicle_gui.cpp --- a/src/vehicle_gui.cpp +++ b/src/vehicle_gui.cpp @@ -681,7 +681,7 @@ struct RefitWindow : public Window { /** * Gets the #StringID to use for displaying capacity. - * @param Cargo and cargo subtype to check for capacity. + * @param option Cargo and cargo subtype to check for capacity. * @return INVALID_STRING_ID if there is no capacity. StringID to use in any other case. * @post String parameters have been set. */ diff --git a/src/viewport_sprite_sorter_sse4.cpp b/src/viewport_sprite_sorter_sse4.cpp --- a/src/viewport_sprite_sorter_sse4.cpp +++ b/src/viewport_sprite_sorter_sse4.cpp @@ -7,7 +7,7 @@ * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see . */ -/** @file viewport_sprite_sorter_sse.cpp Sprite sorter that uses SSE4.1. */ +/** @file viewport_sprite_sorter_sse4.cpp Sprite sorter that uses SSE4.1. */ #ifdef WITH_SSE diff --git a/src/widget.cpp b/src/widget.cpp --- a/src/widget.cpp +++ b/src/widget.cpp @@ -755,7 +755,7 @@ NWidgetBase::NWidgetBase(WidgetType tp) */ /** - * @fn void FillNestedArray(NWidgetBase **array, uint length) + * @fn void NWidgetBase::FillNestedArray(NWidgetBase **array, uint length) * Fill the Window::nested_array array with pointers to nested widgets in the tree. * @param array Base pointer of the array. * @param length Length of the array. @@ -1673,10 +1673,10 @@ NWidgetCore *NWidgetMatrix::GetWidgetFro /** * Get the different offsets that are influenced by scrolling. - * @param [out] start_x The start position in columns (index of the left-most column, swapped in RTL). - * @param [out] start_y The start position in rows. - * @param [out] base_offs_x The base horizontal offset in pixels (X position of the column \a start_x). - * @param [out] base_offs_y The base vertical offset in pixels (Y position of the column \a start_y). + * @param[out] start_x The start position in columns (index of the left-most column, swapped in RTL). + * @param[out] start_y The start position in rows. + * @param[out] base_offs_x The base horizontal offset in pixels (X position of the column \a start_x). + * @param[out] base_offs_y The base vertical offset in pixels (Y position of the column \a start_y). */ void NWidgetMatrix::GetScrollOffsets(int &start_x, int &start_y, int &base_offs_x, int &base_offs_y) { @@ -2805,7 +2805,7 @@ NWidgetContainer *MakeNWidgets(const NWi * @param parts Array with parts of the widgets. * @param count Length of the \a parts array. * @param biggest_index Pointer to biggest nested widget index collected in the tree. - * @param [out] shade_select Pointer to the inserted shade selection widget (\c NULL if not unserted). + * @param[out] shade_select Pointer to the inserted shade selection widget (\c NULL if not unserted). * @return Root of the nested widget tree, a vertical container containing the entire GUI. * @ingroup NestedWidgetParts * @pre \c biggest_index != NULL diff --git a/src/widget_type.h b/src/widget_type.h --- a/src/widget_type.h +++ b/src/widget_type.h @@ -257,7 +257,7 @@ enum NWidgetDisplay { NDB_SHADE_GREY = 3, ///< Shade viewport to grey-scale. NDB_SHADE_DIMMED = 4, ///< Display dimmed colours in the viewport. /* Button dropdown widget. */ - NDB_DROPDOWN_ACTIVE = 5, ///< Dropdown menu of the button dropdown widget is active. @see #NWID_BUTTON_DRPDOWN + NDB_DROPDOWN_ACTIVE = 5, ///< Dropdown menu of the button dropdown widget is active. @see #NWID_BUTTON_DROPDOWN /* Scrollbar widget. */ NDB_SCROLLBAR_UP = 6, ///< Up-button is lowered bit. NDB_SCROLLBAR_DOWN = 7, ///< Down-button is lowered bit. @@ -400,7 +400,7 @@ enum StackedZeroSizePlanes { * There are also a number of special planes (defined in #StackedZeroSizePlanes) that have zero size in one direction (and are stretchable in * the other direction) or have zero size in both directions. They are used to make all child planes of the widget disappear. * Unlike switching between the regular display planes (that all have the same size), switching from or to one of the zero-sized planes means that - * a #Windows::ReInit() is needed to re-initialize the window since its size changes. + * a #Window::ReInit() is needed to re-initialize the window since its size changes. */ class NWidgetStacked : public NWidgetContainer { public: @@ -567,7 +567,7 @@ private: * Nested widget to display a viewport in a window. * After initializing the nested widget tree, call #InitializeViewport(). After changing the window size, * call #UpdateViewportCoordinates() eg from Window::OnResize(). - * If the #display_flags field contains the #ND_NO_TRANSPARENCY bit, the viewport will disable transparency. + * If the #disp_flags field contains the #ND_NO_TRANSPARENCY bit, the viewport will disable transparency. * Shading to grey-scale is controlled with the #ND_SHADE_GREY bit (used for B&W news papers), the #ND_SHADE_DIMMED gives dimmed colours (for colour news papers). * @todo Class derives from #NWidgetCore, but does not use #colour, #widget_data, or #tool_tip. * @ingroup NestedWidgets @@ -1124,8 +1124,8 @@ static inline NWidgetPart NWidget(Widget /** * Widget part function for starting a new horizontal container, vertical container, or spacer widget. - * @param tp Type of the new nested widget, #NWID_HORIZONTAL(_LTR), #NWID_VERTICAL, #NWID_SPACER, #NWID_SELECTION, and #NWID_MATRIX. - * @param cont_flags Flags for the containers (#NWID_HORIZONTAL(_LTR) and #NWID_VERTICAL). + * @param tp Type of the new nested widget, #NWID_HORIZONTAL, #NWID_VERTICAL, #NWID_SPACER, #NWID_SELECTION, and #NWID_MATRIX. + * @param cont_flags Flags for the containers (#NWID_HORIZONTAL and #NWID_VERTICAL). * @ingroup NestedWidgetParts */ static inline NWidgetPart NWidget(WidgetType tp, NWidContainerFlags cont_flags = NC_NONE) diff --git a/src/widgets/cheat_widget.h b/src/widgets/cheat_widget.h --- a/src/widgets/cheat_widget.h +++ b/src/widgets/cheat_widget.h @@ -12,7 +12,7 @@ #ifndef WIDGETS_CHEAT_WIDGET_H #define WIDGETS_CHEAT_WIDGET_H -/** Widgets of the #CheatWindow class.. */ +/** Widgets of the #CheatWindow class. */ enum CheatWidgets { WID_C_PANEL, ///< Panel where all cheats are shown in. }; diff --git a/src/widgets/dropdown.cpp b/src/widgets/dropdown.cpp --- a/src/widgets/dropdown.cpp +++ b/src/widgets/dropdown.cpp @@ -111,7 +111,6 @@ struct DropdownWindow : Window { * @param size Size of the dropdown menu window. * @param wi_colour Colour of the parent widget. * @param scroll Dropdown menu has a scrollbar. - * @param widget Widgets of the dropdown menu window. */ DropdownWindow(Window *parent, const DropDownList *list, int selected, int button, bool instant_close, const Point &position, const Dimension &size, Colours wi_colour, bool scroll) : Window(&_dropdown_desc) @@ -182,7 +181,7 @@ struct DropdownWindow : Window { /** * Find the dropdown item under the cursor. - * @param value [out] Selected item, if function returns \c true. + * @param[out] value Selected item, if function returns \c true. * @return Cursor points to a dropdown item. */ bool GetDropDownItem(int &value) diff --git a/src/window.cpp b/src/window.cpp --- a/src/window.cpp +++ b/src/window.cpp @@ -49,7 +49,7 @@ enum ViewportAutoscrolling { }; static Point _drag_delta; ///< delta between mouse cursor and upper left corner of dragged window -static Window *_mouseover_last_w = NULL; ///< Window of the last #MOUSEOVER event. +static Window *_mouseover_last_w = NULL; ///< Window of the last OnMouseOver event. static Window *_last_scroll_window = NULL; ///< Window of the last scroll event. /** List of windows opened at the screen sorted from the front. */ @@ -1115,7 +1115,7 @@ Window *FindWindowById(WindowClass cls, /** * Find any window by its class. Useful when searching for a window that uses - * the window number as a #WindowType, like #WC_SEND_NETWORK_MSG. + * the window number as a #WindowClass, like #WC_SEND_NETWORK_MSG. * @param cls Window class * @return Pointer to the found window, or \c NULL if not available */ @@ -1430,7 +1430,6 @@ static void BringWindowToFront(Window *w /** * Initializes the data (except the position and initial size) of a new Window. - * @param desc Window description. * @param window_number Number being assigned to the new window * @return Window pointer of the newly created window * @pre If nested widgets are used (\a widget is \c NULL), #nested_root and #nested_array_size must be initialized. @@ -2000,7 +1999,7 @@ static void HandleMouseOver() { Window *w = FindWindowFromPt(_cursor.pos.x, _cursor.pos.y); - /* We changed window, put a MOUSEOVER event to the last window */ + /* We changed window, put an OnMouseOver event to the last window */ if (_mouseover_last_w != NULL && _mouseover_last_w != w) { /* Reset mouse-over coordinates of previous window */ Point pt = { -1, -1 };