diff --git a/src/game/game_text.cpp b/src/game/game_text.cpp index dd79e9c85e..d3e16a876a 100644 --- a/src/game/game_text.cpp +++ b/src/game/game_text.cpp @@ -162,15 +162,20 @@ struct StringNameWriter : HeaderWriter { */ class LanguageScanner : protected FileScanner { private: - std::weak_ptr gs; - std::string exclude; + std::weak_ptr gs; ///< The (already) loaded game strings. + std::string exclude; ///< The file name to exclude during scanning. public: - /** Initialise */ + /** + * Initialise the scanner. + * @param gs The (already) loaded game strings to add to. + * @param exclude The file name to exclude during sanning. + */ LanguageScanner(std::weak_ptr gs, const std::string &exclude) : gs(gs), exclude(exclude) {} /** - * Scan. + * Actually run the scan. + * @param directory The directory to scan in. */ void Scan(const std::string &directory) { diff --git a/src/gamelog.cpp b/src/gamelog.cpp index 04b1d0af21..13fafc5fd3 100644 --- a/src/gamelog.cpp +++ b/src/gamelog.cpp @@ -43,6 +43,7 @@ Gamelog::~Gamelog() /** * Return the revision string for the current client version, for use in gamelog. + * @return The revision string. */ static std::string GetGamelogRevisionString() { @@ -359,6 +360,7 @@ void Gamelog::Emergency() /** * Finds out if current game is a loaded emergency savegame. + * @return \c true iff an action with GLCT_EMERGENCY change exists. */ bool Gamelog::TestEmergency() { @@ -584,8 +586,9 @@ void Gamelog::GRFAddList(const GRFConfigList &newg) } /** - * Generates GRFList - * @param grfc the GRFConfigList. + * Generates GRFList. + * @param grfc The GRFConfigList. + * @return The list with NewGRFs to log.. */ static std::vector GenerateGRFList(const GRFConfigList &grfc) { diff --git a/src/genworld_gui.cpp b/src/genworld_gui.cpp index fddc29095a..0eb42f4dd9 100644 --- a/src/genworld_gui.cpp +++ b/src/genworld_gui.cpp @@ -55,6 +55,7 @@ enum GenerateLandscapeWindowMode : uint8_t { /** * Get the map height limit, or if set to "auto", the absolute limit. + * @return The maximum map height. */ static uint GetMapHeightLimit() { diff --git a/src/gfxinit.cpp b/src/gfxinit.cpp index 8578925817..a3a5b91a6e 100644 --- a/src/gfxinit.cpp +++ b/src/gfxinit.cpp @@ -465,7 +465,9 @@ MD5File::ChecksumResult MD5File::CheckMD5(Subdirectory subdir, size_t max_size) /** Names corresponding to the GraphicsFileType */ static const std::string_view _graphics_file_names[] = { "base", "logos", "arctic", "tropical", "toyland", "extra" }; -/** Implementation */ +/* Implementation */ + +/** @copydoc BaseSet::GetFilenames */ template <> /* static */ std::span BaseSet::GetFilenames() { diff --git a/src/graph_gui.cpp b/src/graph_gui.cpp index 6e5c22929a..566aaeea29 100644 --- a/src/graph_gui.cpp +++ b/src/graph_gui.cpp @@ -343,6 +343,7 @@ protected: * Get width for Y labels. * @param current_interval Interval that contains all of the graph data. * @param num_hori_lines Number of horizontal lines to be drawn. + * @return The width in pixels. */ uint GetYLabelWidth(ValuesInterval current_interval, int num_hori_lines) const { @@ -2050,7 +2051,7 @@ static std::unique_ptr MakePerformanceDetailPanels() return vert; } -/** Make a number of rows with buttons for each company for the performance rating detail window. */ +/** Make a number of rows with buttons for each company for the performance rating detail window. @copydoc NWidgetFunctionType */ std::unique_ptr MakeCompanyButtonRowsGraphGUI() { return MakeCompanyButtonRows(WID_PRD_COMPANY_FIRST, WID_PRD_COMPANY_LAST, COLOUR_BROWN, 8, STR_PERFORMANCE_DETAIL_SELECT_COMPANY_TOOLTIP); diff --git a/src/group_cmd.cpp b/src/group_cmd.cpp index 033913d9a2..08a4fd538e 100644 --- a/src/group_cmd.cpp +++ b/src/group_cmd.cpp @@ -183,6 +183,7 @@ uint16_t GroupStatistics::GetNumEngines(EngineID engine) const /** * Add a vehicle's last year profit to the profit sum of its group. + * @param v The vehicle to update the statistics for. */ /* static */ void GroupStatistics::AddProfitLastYear(const Vehicle *v) { @@ -195,6 +196,7 @@ uint16_t GroupStatistics::GetNumEngines(EngineID engine) const /** * Add a vehicle to the profit sum of its group. + * @param v The vehicle to update the statistics for. */ /* static */ void GroupStatistics::VehicleReachedMinAge(const Vehicle *v) { @@ -684,6 +686,7 @@ CommandCost CmdRemoveAllVehiclesGroup(DoCommandFlags flags, GroupID group_id) * @param group_id Group ID. * @param primary Set primary instead of secondary colour * @param colour Colour. + * @return The (zero) cost or error. */ CommandCost CmdSetGroupLivery(DoCommandFlags flags, GroupID group_id, bool primary, Colours colour) { diff --git a/src/heightmap.cpp b/src/heightmap.cpp index 24b83c96b2..39865b3333 100644 --- a/src/heightmap.cpp +++ b/src/heightmap.cpp @@ -65,6 +65,10 @@ static inline bool IsValidHeightmapDimension(size_t width, size_t height) /** * Convert RGB colours to Greyscale using 29.9% Red, 58.7% Green, 11.4% Blue * (average luminosity formula, NTSC Colour Space) + * @param red The red component of a colour. + * @param green The green component of a colour. + * @param blue The blue component of a colour. + * @return The greyscale conversion of a colour. */ static inline uint8_t RGBToGreyscale(uint8_t red, uint8_t green, uint8_t blue) { @@ -78,6 +82,9 @@ static inline uint8_t RGBToGreyscale(uint8_t red, uint8_t green, uint8_t blue) /** * The PNG Heightmap loader. + * @param map The map to write data to. + * @param png_ptr The PNG file to load. + * @param info_ptr Metadata about the loaded PNG. */ static void ReadHeightmapPNGImageData(std::span map, png_structp png_ptr, png_infop info_ptr) { @@ -137,6 +144,11 @@ static void ReadHeightmapPNGImageData(std::span map, png_structp png_pt * Reads the heightmap and/or size of the heightmap from a PNG file. * If map == nullptr only the size of the PNG is read, otherwise a map * with greyscale pixels is allocated and assigned to *map. + * @param filename Name of the file to load. + * @param[out] x Length of the image. + * @param[out] y Height of the image. + * @param[in,out] map If not \c nullptr, destination to store the loaded block of image data. + * @return Whether loading was successful. */ static bool ReadHeightmapPNG(std::string_view filename, uint *x, uint *y, std::vector *map) { @@ -203,6 +215,9 @@ static bool ReadHeightmapPNG(std::string_view filename, uint *x, uint *y, std::v /** * The BMP Heightmap loader. + * @param map The image to load into. + * @param info Metadata about the image. + * @param data The actual BMP data. */ static void ReadHeightmapBMPImageData(std::span map, const BmpInfo &info, const BmpData &data) { @@ -258,6 +273,11 @@ static void ReadHeightmapBMPImageData(std::span map, const BmpInfo &inf * Reads the heightmap and/or size of the heightmap from a BMP file. * If map == nullptr only the size of the BMP is read, otherwise a map * with greyscale pixels is allocated and assigned to *map. + * @param filename Name of the file to load. + * @param[out] x Length of the image. + * @param[out] y Height of the image. + * @param[in,out] map If not \c nullptr, destination to store the loaded block of image data. + * @return Whether loading was successful. */ static bool ReadHeightmapBMP(std::string_view filename, uint *x, uint *y, std::vector *map) { @@ -512,7 +532,8 @@ bool GetHeightmapDimensions(DetailedFileType dft, std::string_view filename, uin * to a landscape representing the heightmap. * It converts pixels to height. The brighter, the higher. * @param dft Type of image file. - * @param filename of the heightmap file to be imported + * @param filename of the heightmap file to be imported. + * @return \c true iff the heightmap could be loaded. */ bool LoadHeightmap(DetailedFileType dft, std::string_view filename) { diff --git a/src/highscore_gui.cpp b/src/highscore_gui.cpp index 47f5644f30..807c1de761 100644 --- a/src/highscore_gui.cpp +++ b/src/highscore_gui.cpp @@ -67,11 +67,15 @@ struct EndGameHighScoreBaseWindow : Window { } } - /** Return the coordinate of the screen such that a window of 640x480 is centered at the screen. */ - Point GetTopLeft(int x, int y) + /** + * Return the coordinate of the screen such that a window of a given size is centered at the screen. + * @param width The width of the image. + * @param height The height of the image. + * @return The top left coordinate. + */ + Point GetTopLeft(int width, int height) { - Point pt = {std::max(0, (_screen.width / 2) - (x / 2)), std::max(0, (_screen.height / 2) - (y / 2))}; - return pt; + return {std::max(0, (_screen.width / 2) - (width / 2)), std::max(0, (_screen.height / 2) - (height / 2))}; } void OnClick([[maybe_unused]] Point pt, [[maybe_unused]] WidgetID widget, [[maybe_unused]] int click_count) override @@ -239,6 +243,8 @@ static WindowDesc _endgame_desc( * Show the highscore table for a given difficulty. When called from * endgame ranking is set to the top5 element that was newly added * and is thus highlighted + * @param difficulty The difficulty level to show the high score for. + * @param ranking The ranking to show the local company at. */ void ShowHighscoreTable(int difficulty, int8_t ranking) { @@ -260,6 +266,7 @@ void ShowEndGameChart() new EndGameWindow(_endgame_desc); } +/** Yearly timer to check whether we want to show the end game chart. */ static const IntervalTimer _check_end_game({TimerGameCalendar::Trigger::Year, TimerGameCalendar::Priority::None}, [](auto) { /* 0 = never */ diff --git a/src/hotkeys.h b/src/hotkeys.h index 75b31b641b..e4d1ce5720 100644 --- a/src/hotkeys.h +++ b/src/hotkeys.h @@ -53,6 +53,7 @@ private: /** * Dummy private copy constructor to prevent compilers from * copying the structure, which fails due to _hotkey_lists. + * @param other The list not to copy from. */ HotkeyList(const HotkeyList &other); }; diff --git a/src/industry.h b/src/industry.h index 62f1c72400..5aabd9777c 100644 --- a/src/industry.h +++ b/src/industry.h @@ -260,6 +260,7 @@ struct Industry : IndustryPool::PoolItem<&_industry_pool> { * Get the count of industries for this type. * @param type IndustryType to query * @pre type < NUM_INDUSTRYTYPES + * @return The number of industries of the given type. */ static inline uint16_t GetIndustryTypeCount(IndustryType type) { diff --git a/src/industry_cmd.cpp b/src/industry_cmd.cpp index 6da7a0e9d8..52319312dd 100644 --- a/src/industry_cmd.cpp +++ b/src/industry_cmd.cpp @@ -1616,6 +1616,10 @@ static bool CheckCanTerraformSurroundingTiles(TileIndex tile, uint height, int i /** * This function tries to flatten out the land below an industry, without * damaging the surroundings too much. + * @param tile The tile to place the industry's starting point at. + * @param flags Flags describing how to execute this command. + * @param layout The layout to build. + * @return \c true iff the industry can be built at this location. */ static bool CheckIfCanLevelIndustryPlatform(TileIndex tile, DoCommandFlags flags, const IndustryTileLayout &layout) { diff --git a/src/library_loader.h b/src/library_loader.h index 32c561bd90..1d4c70c88d 100644 --- a/src/library_loader.h +++ b/src/library_loader.h @@ -33,6 +33,7 @@ public: /** * Load a library with the given filename. + * @param filename The library to open. */ explicit LibraryLoader(const std::string &filename) { @@ -88,6 +89,7 @@ private: * Should set error if any error occurred. * * @param filename The filename of the library to open. + * @return Handle to the opened library. */ void *OpenLibrary(const std::string &filename); @@ -102,6 +104,7 @@ private: * Should set error if any error occurred. * * @param symbol_name The name of the symbol to get. + * @return The loaded symbol, or \c nullptr when no symbol was loaded. */ void *GetSymbol(const std::string &symbol_name); diff --git a/src/map_func.h b/src/map_func.h index 6fb8cb71b8..54160989a9 100644 --- a/src/map_func.h +++ b/src/map_func.h @@ -71,11 +71,13 @@ public: /** * Implicit conversion to the TileIndex. + * @return The converted tile index. */ [[debug_inline]] inline constexpr operator TileIndex() const { return this->tile; } /** * Implicit conversion to the uint for bounds checking. + * @return The (unsigned) integer representation of the tile location. */ [[debug_inline]] inline constexpr operator uint() const { return this->tile.base(); } @@ -314,7 +316,8 @@ public: /** * 'Wraps' the given "tile" so it is within the map. * It does this by masking the 'high' bits of. - * @param tile the tile to 'wrap' + * @param tile the tile to 'wrap'. + * @return The wrapped tile. */ static inline TileIndex WrapToMap(TileIndex tile) { diff --git a/src/misc.cpp b/src/misc.cpp index ea215f354f..04c93d2a0d 100644 --- a/src/misc.cpp +++ b/src/misc.cpp @@ -62,6 +62,8 @@ void InitializeOldNames(); * It isn't as much of an unique ID but more a hashed digest of a random * string and a time. It is very likely to be unique, but it does not follow * any UUID standard. + * @param subject What to create the ID for. + * @return The generated ID. */ std::string GenerateUid(std::string_view subject) { diff --git a/src/music.cpp b/src/music.cpp index ee33585c04..165728bac8 100644 --- a/src/music.cpp +++ b/src/music.cpp @@ -77,6 +77,7 @@ static const std::string_view _music_file_names[] = { /** Make sure we aren't messing things up. */ static_assert(lengthof(_music_file_names) == NUM_SONGS_AVAILABLE); +/** @copydoc BaseSet::GetFilenames */ template <> /* static */ std::span BaseSet::GetFilenames() { diff --git a/src/music_gui.cpp b/src/music_gui.cpp index 5842954cc8..fc371e7703 100644 --- a/src/music_gui.cpp +++ b/src/music_gui.cpp @@ -293,26 +293,38 @@ void MusicSystem::CheckStatus() if (this->IsPlaying() && !MusicDriver::GetInstance()->IsSongPlaying()) this->Next(); } -/** Is the player getting music right now? */ +/** + * Is the player getting music right now? + * @return \c true iff a song is playing. + */ bool MusicSystem::IsPlaying() const { return _settings_client.music.playing && !this->active_playlist.empty(); } -/** Is shuffle mode enabled? */ +/** + * Is shuffle mode enabled? + * @return \c true iff shuffling is enabled. + */ bool MusicSystem::IsShuffle() const { return _settings_client.music.shuffle; } -/** Return the current song, or a dummy if none */ +/** + * Return the current song, or a dummy if none. + * @return The currently playing song. + */ MusicSystem::PlaylistEntry MusicSystem::GetCurrentSong() const { if (!this->IsPlaying()) return PlaylistEntry(BaseMusic::GetUsedSet(), 0); return this->active_playlist[this->playlist_position]; } -/** Is one of the custom playlists selected? */ +/** + * Is one of the custom playlists selected? + * @return \c true iff one of the custom playlists is selected. + */ bool MusicSystem::IsCustomPlaylist() const { return (this->selected_playlist == PLCH_CUSTOM1) || (this->selected_playlist == PLCH_CUSTOM2); diff --git a/src/sound.cpp b/src/sound.cpp index 31a7edea1b..0670ad136e 100644 --- a/src/sound.cpp +++ b/src/sound.cpp @@ -266,6 +266,7 @@ void SndConfirmBeep() /** Names corresponding to the sound set's files */ static const std::string_view _sound_file_names[] = { "samples" }; +/** @copydoc BaseSet::GetFilenames */ template <> /* static */ std::span BaseSet::GetFilenames() { diff --git a/src/spriteloader/spriteloader.hpp b/src/spriteloader/spriteloader.hpp index 4ecac9b8fe..6c99c71c27 100644 --- a/src/spriteloader/spriteloader.hpp +++ b/src/spriteloader/spriteloader.hpp @@ -134,11 +134,16 @@ public: /** * Can the sprite encoder make use of RGBA sprites? + * @return \c true iff RGBA sprites are supported. */ virtual bool Is32BppSupported() = 0; /** * Convert a sprite from the loader to our own format. + * @param sprite_type The type of sprite to load. + * @param sprite The sprites to load. + * @param allocator The allocator for the sprite's memory. + * @return The encoded sprite. */ virtual Sprite *Encode(SpriteType sprite_type, const SpriteLoader::SpriteCollection &sprite, SpriteAllocator &allocator) = 0;