diff --git a/src/signal.cpp b/src/signal.cpp index f188382e82..a714a27f25 100644 --- a/src/signal.cpp +++ b/src/signal.cpp @@ -65,7 +65,10 @@ private: } data[items]; public: - /** Constructor - just set default values and 'name' */ + /** + * Constructor - just set default values and 'name' + * @param name The name of the set. + */ SmallSet(std::string_view name) : name(name) { } /** Reset variables to default values */ @@ -190,7 +193,11 @@ static SmallSet _tbdset("_tbdset"); ///< set of static SmallSet _globset("_globset"); ///< set of places to be updated in following runs -/** Check whether there is a train on rail, not in a depot */ +/** + * Check whether there is a train on rail, not in a depot. + * @param v The vehicle to check. + * @return \c true when the vehicle is a train that's not in a depot. + */ static bool IsTrainAndNotInDepot(const Vehicle *v) { return v->type == VEH_TRAIN && Train::From(v)->track != TRACK_BIT_DEPOT; diff --git a/src/signal_func.h b/src/signal_func.h index d8b9d3ba03..678aa243ac 100644 --- a/src/signal_func.h +++ b/src/signal_func.h @@ -18,6 +18,8 @@ /** * Maps a trackdir to the bit that stores its status in the map arrays, in the * direction along with the trackdir. + * @param trackdir The track dir to consider. + * @return Bitmask of the storage of the signal in the associated trackdir in the map array. */ inline uint8_t SignalAlongTrackdir(Trackdir trackdir) { @@ -28,6 +30,8 @@ inline uint8_t SignalAlongTrackdir(Trackdir trackdir) /** * Maps a trackdir to the bit that stores its status in the map arrays, in the * direction against the trackdir. + * @param trackdir The track dir to consider. + * @return Bitmask of the storage of the signal in the associated trackdir in the map array. */ inline uint8_t SignalAgainstTrackdir(Trackdir trackdir) { @@ -38,6 +42,8 @@ inline uint8_t SignalAgainstTrackdir(Trackdir trackdir) /** * Maps a Track to the bits that store the status of the two signals that can * be present on the given track. + * @param track The track to consider. + * @return Bitmask of the storage of the signal in the associated track in the map array. */ inline uint8_t SignalOnTrack(Track track) { diff --git a/src/signature.cpp b/src/signature.cpp index 081f798139..87e931a5ca 100644 --- a/src/signature.cpp +++ b/src/signature.cpp @@ -189,6 +189,7 @@ static bool ValidateSchema(const nlohmann::json &signatures, const std::string & * Validate that the signatures mentioned in the signature file are matching * the files in question. * + * @param filename The path to the file to validate. * @return True iff the files in the signature file passed validation. */ static bool _ValidateSignatureFile(const std::string &filename) @@ -262,6 +263,7 @@ static bool _ValidateSignatureFile(const std::string &filename) * @note if ALLOW_INVALID_SIGNATURE is defined, this function will always * return true (but will still report any errors in the console). * + * @param filename The path to the file to validate. * @return True iff the files in the signature file passed validation. */ bool ValidateSignatureFile(const std::string &filename) diff --git a/src/signs_gui.cpp b/src/signs_gui.cpp index f63d94d17d..5af4fc5c02 100644 --- a/src/signs_gui.cpp +++ b/src/signs_gui.cpp @@ -174,6 +174,7 @@ struct SignListWindow : Window, SignList { * the edit widget is not updated by this function. Depending on if the * new string is zero-length or not the clear button is made * disabled/enabled. The sign list is updated according to the new filter. + * @param new_filter_string The new terms for filtering. */ void SetFilterString(std::string_view new_filter_string) { diff --git a/src/smallmap_gui.cpp b/src/smallmap_gui.cpp index 2f039c512d..3c87b25758 100644 --- a/src/smallmap_gui.cpp +++ b/src/smallmap_gui.cpp @@ -703,6 +703,7 @@ protected: /** * Return number of columns that can be displayed in \a width pixels. + * @param width The available width. * @return Number of columns to display. */ inline uint GetNumberColumnsLegend(uint width) const diff --git a/src/social_integration.h b/src/social_integration.h index ed7e59f7ed..7314733e06 100644 --- a/src/social_integration.h +++ b/src/social_integration.h @@ -38,6 +38,7 @@ class SocialIntegration { public: /** * Get the list of loaded social integration plugins. + * @return The loaded plugins. */ static std::vector GetPlugins(); @@ -63,16 +64,22 @@ public: /** * Event: user entered the Scenario Editor. + * @param map_width The width of the entered scenario. + * @param map_height The width of the entered scenario. */ static void EventEnterScenarioEditor(uint map_width, uint map_height); /** * Event: user entered a singleplayer game. + * @param map_width The width of the entered map. + * @param map_height The width of the entered map. */ static void EventEnterSingleplayer(uint map_width, uint map_height); /** * Event: user entered a multiplayer game. + * @param map_width The width of the entered map. + * @param map_height The width of the entered map. */ static void EventEnterMultiplayer(uint map_width, uint map_height); diff --git a/src/sprite.h b/src/sprite.h index 900da62989..24aeeb2922 100644 --- a/src/sprite.h +++ b/src/sprite.h @@ -37,7 +37,10 @@ struct DrawTileSeqStruct : SpriteBounds { constexpr DrawTileSeqStruct(int8_t origin_x, int8_t origin_y, int8_t origin_z, uint8_t extent_x, uint8_t extent_y, uint8_t extent_z, PalSpriteID image) : SpriteBounds({origin_x, origin_y, origin_z}, {extent_x, extent_y, extent_z}, {}), image(image) {} - /** Check whether this is a parent sprite with a boundingbox. */ + /** + * Check whether this is a parent sprite with a boundingbox. + * @return \c true iff this sprite is the parent sprite. + */ inline bool IsParentSprite() const { return static_cast(this->origin.z) != 0x80; diff --git a/src/spriteloader/sprite_file.cpp b/src/spriteloader/sprite_file.cpp index 47db5d425f..68b904ddc2 100644 --- a/src/spriteloader/sprite_file.cpp +++ b/src/spriteloader/sprite_file.cpp @@ -16,6 +16,7 @@ extern const std::array _grf_cont_v2_sig = {'G', 'R', 'F', 0x82, 0x0 /** * Get the container version of the currently opened GRF file. + * @param file The file that is being opened. * @return Container version of the GRF file or 0 if the file is corrupt/no GRF file. */ static uint8_t GetGRFContainerVersion(SpriteFile &file) diff --git a/src/station.cpp b/src/station.cpp index 76715d656d..d60c275035 100644 --- a/src/station.cpp +++ b/src/station.cpp @@ -166,8 +166,9 @@ Station::~Station() /** * Invalidating of the JoinStation window has to be done * after removing item from the pool. + * @copydoc Pool::PoolItem::PostDestructor */ -void BaseStation::PostDestructor(size_t) +void BaseStation::PostDestructor([[maybe_unused]] size_t index) { InvalidateWindowData(WC_SELECT_STATION, 0, 0); } @@ -226,6 +227,8 @@ RoadStop *Station::GetPrimaryRoadStop(const RoadVehicle *v) const /** * Called when new facility is built on the station. If it is the first facility * it initializes also 'xy' and 'random_bits' members + * @param new_facility_bit The new facility. + * @param facil_xy The location where this facility is built. */ void Station::AddFacility(StationFacility new_facility_bit, TileIndex facil_xy) { @@ -241,7 +244,7 @@ void Station::AddFacility(StationFacility new_facility_bit, TileIndex facil_xy) /** * Marks the tiles of the station as dirty. - * + * @param cargo_change Whether only cargo amounts changed. * @ingroup dirty */ void Station::MarkTilesDirty(bool cargo_change) const diff --git a/src/station_base.h b/src/station_base.h index d72b550af4..a43954d8b9 100644 --- a/src/station_base.h +++ b/src/station_base.h @@ -400,7 +400,10 @@ struct Airport : public TileArea { return this->GetSpec()->fsm; } - /** Check if this airport has at least one hangar. */ + /** + * Check if this airport has at least one hangar. + * @return \c true iff there are one or more hangars. + */ inline bool HasHangar() const { return !this->GetSpec()->depots.empty(); @@ -471,7 +474,10 @@ struct Airport : public TileArea { return htt->hangar_num; } - /** Get the number of hangars on this airport. */ + /** + * Get the number of hangars on this airport. + * @return The number of unique hangars. + */ inline uint GetNumHangars() const { uint num = 0; diff --git a/src/station_cmd.cpp b/src/station_cmd.cpp index 9b9846dec8..62fff2bccd 100644 --- a/src/station_cmd.cpp +++ b/src/station_cmd.cpp @@ -529,6 +529,7 @@ static void ShowRejectOrAcceptNews(const Station *st, CargoTypes cargoes, bool r * @param w X extent of the area * @param h Y extent of the area * @param rad Search radius in addition to the given area + * @return Array of production per cargo type. */ CargoArray GetProductionAroundTiles(TileIndex north_tile, int w, int h, int rad) { @@ -2858,6 +2859,7 @@ CommandCost CmdOpenCloseAirport(DoCommandFlags flags, StationID station_id) * @param station station ID * @param include_company If true only check vehicles of \a company, if false only check vehicles of other companies * @param company company ID + * @return \c true when at least one vehicle is ordered to go to this station. */ bool HasStationInUse(StationID station, bool include_company, CompanyID company) { diff --git a/src/station_gui.cpp b/src/station_gui.cpp index 0f27a0abe5..38f5cd1c9f 100644 --- a/src/station_gui.cpp +++ b/src/station_gui.cpp @@ -967,46 +967,55 @@ public: /** * Get the station ID for this entry. + * @return The station this cargo is at. */ StationID GetStation() const { return this->station; } /** * Get the cargo type for this entry. + * @return The type of cargo. */ CargoType GetCargo() const { return this->cargo; } /** * Get the cargo count for this entry. + * @return The amount of cargo. */ uint GetCount() const { return this->count; } /** * Get the parent entry for this entry. + * @return The parent entry, can be \c nullptr. */ CargoDataEntry *GetParent() const { return this->parent; } /** * Get the number of children for this entry. + * @return The number of children. */ uint GetNumChildren() const { return this->num_children; } /** * Get an iterator pointing to the begin of the set of children. + * @return Iterator at the begin of our children. */ CargoDataSet::iterator Begin() const { return this->children->begin(); } /** * Get an iterator pointing to the end of the set of children. + * @return Iterator at the end of our children. */ CargoDataSet::iterator End() const { return this->children->end(); } /** * Has this entry transfers. + * @return \c true iff the transfers state has been set. */ bool HasTransfers() const { return this->transfers; } /** * Set the transfers state. + * @param value The new transfers state. */ void SetTransfers(bool value) { this->transfers = value; } diff --git a/src/statusbar_gui.cpp b/src/statusbar_gui.cpp index 87b92d4ca2..685bca734c 100644 --- a/src/statusbar_gui.cpp +++ b/src/statusbar_gui.cpp @@ -227,6 +227,7 @@ static WindowDesc _main_status_desc( /** * Checks whether the news ticker is currently being used. + * @return \c true iff the status bar exists and the ticker is in use. */ bool IsNewsTickerShown() { diff --git a/src/story_gui.cpp b/src/story_gui.cpp index b39a157f21..fe6419a7c3 100644 --- a/src/story_gui.cpp +++ b/src/story_gui.cpp @@ -155,6 +155,7 @@ protected: /** * Check if the selected page is also the first available page. + * @return \c true iff the selected page is the first one. */ bool IsFirstPageSelected() { @@ -166,6 +167,7 @@ protected: /** * Check if the selected page is also the last available page. + * @return \c true iff the selected page is the last one. */ bool IsLastPageSelected() { @@ -242,6 +244,7 @@ protected: /** * Builds the page selector drop down list. + * @return The created drop down list. */ DropDownList BuildDropDownList() const { @@ -263,6 +266,7 @@ protected: /** * Get the width available for displaying content on the page panel. + * @return The width in pixels. */ uint GetAvailablePageContentWidth() const { diff --git a/src/strgen/strgen_base.cpp b/src/strgen/strgen_base.cpp index 94e784a78c..df96c72e56 100644 --- a/src/strgen/strgen_base.cpp +++ b/src/strgen/strgen_base.cpp @@ -155,6 +155,7 @@ uint32_t StringData::Version() const /** * Count the number of tab elements that are in use. * @param tab The tab to count the elements of. + * @return The number of elements in this tab. */ size_t StringData::CountInUse(size_t tab) const { diff --git a/src/string.cpp b/src/string.cpp index f2ba7163cb..34d7f5375a 100644 --- a/src/string.cpp +++ b/src/string.cpp @@ -184,6 +184,7 @@ void StrMakeValidInPlace(std::string &str, StringValidationSettings settings) * question mark, as well as determining what characters are deemed invalid. * @param str The string to validate. * @param settings The settings for the string validation. + * @return A copy of the valid characters of the given string. */ std::string StrMakeValid(std::string_view str, StringValidationSettings settings) { @@ -201,6 +202,7 @@ std::string StrMakeValid(std::string_view str, StringValidationSettings settings * std::string_view's constructor will assume a C-string that ends with a NUL terminator, which is one of the things * we are checking. * @param str Span of chars to validate. + * @return \c true iff the string is valid. */ bool StrValid(std::span str) { diff --git a/src/strings.cpp b/src/strings.cpp index 140bc23a3c..cd072177ef 100644 --- a/src/strings.cpp +++ b/src/strings.cpp @@ -2039,6 +2039,7 @@ bool LanguagePackHeader::IsValid() const /** * Check whether a translation is sufficiently finished to offer it to the public. + * @return \c true iff there are less than 25% missing strings. */ bool LanguagePackHeader::IsReasonablyFinished() const { diff --git a/src/strings_func.h b/src/strings_func.h index 5b8fcaafd1..5b61105cd2 100644 --- a/src/strings_func.h +++ b/src/strings_func.h @@ -59,6 +59,7 @@ inline StringID MakeStringID(StringTab tab, StringIndexInTab index) /** * Prepare the string parameters for the next formatting run, resetting the type information. * This is only necessary if parameters are reused for multiple format runs. + * @param args The parameters to prepare. */ static inline void PrepareArgsForNextRun(std::span args) { diff --git a/src/strings_internal.h b/src/strings_internal.h index a94216d0bb..149b664d4f 100644 --- a/src/strings_internal.h +++ b/src/strings_internal.h @@ -29,12 +29,18 @@ public: /** * Create a new StringParameters instance that can reference part of the data of * the given parent instance. + * @param parent The parent we are a subset from. + * @param size The number of elements from the parent at its offset to take. */ StringParameters(StringParameters &parent, size_t size) : parent(&parent), parameters(parent.parameters.subspan(parent.offset, size)) {} + /** + * Create a new StringParameters instance with the given parameters. + * @param parameters The actual parameters. + */ StringParameters(std::span parameters = {}) : parameters(parameters) {} void SetTypeOfNextParameter(char32_t type) { this->next_type = type; } @@ -149,19 +155,29 @@ public: return StringParameters(this->parameters.subspan(offset, this->parameters.size() - offset)); } - /** Return the amount of elements which can still be read. */ + /** + * Return the amount of elements which can still be read. + * @return The number of parameters minus the current offset. + */ size_t GetDataLeft() const { return this->parameters.size() - this->offset; } - /** Return the number of parameters. */ + /** + * Return the number of parameters. + * @return The parameter count. + */ size_t GetNumParameters() const { return this->parameters.size(); } - /** Get the type of a specific element. */ + /** + * Get the type of a specific element. + * @param offset The offset to get the type for. + * @return The type. + */ char32_t GetTypeAtOffset(size_t offset) const { assert(offset < this->parameters.size()); diff --git a/src/survey.cpp b/src/survey.cpp index 1953b45ce0..67e16870b4 100644 --- a/src/survey.cpp +++ b/src/survey.cpp @@ -115,6 +115,7 @@ static const std::string _vehicle_type_to_string[] = { * - _company_settings * - _win32_settings * As such, they are not part of this list. + * @return The table of generic settings. */ static auto &GenericSettingTables() { diff --git a/src/textfile_gui.cpp b/src/textfile_gui.cpp index 9a00bf1e6a..7cf14970df 100644 --- a/src/textfile_gui.cpp +++ b/src/textfile_gui.cpp @@ -847,6 +847,8 @@ static std::vector Xunzip(std::span input) /** * Loads the textfile text from file and setup #lines. + * @param textfile The filename of the file to load. + * @param dir The sub directory to find the file in. */ /* virtual */ void TextfileWindow::LoadTextfile(const std::string &textfile, Subdirectory dir) { diff --git a/src/tilearea.cpp b/src/tilearea.cpp index 94ab5f5ee7..62a17312a8 100644 --- a/src/tilearea.cpp +++ b/src/tilearea.cpp @@ -230,6 +230,7 @@ bool DiagonalTileArea::Contains(TileIndex tile) const /** * Move ourselves to the next tile in the rectangle on the map. + * @return Reference to this iterator. */ TileIterator &DiagonalTileIterator::operator++() { @@ -296,9 +297,7 @@ TileIterator &DiagonalTileIterator::operator++() return std::make_unique(corner1, corner2); } -/** - * See SpiralTileSequence constructor for description. - */ +/** Create the iterator. @copydoc SpiralTileSequence::SpiralTileSequence(TileIndex, uint) */ SpiralTileIterator::SpiralTileIterator(TileIndex center, uint diameter) : max_radius(diameter / 2), cur_radius(0), @@ -325,9 +324,7 @@ SpiralTileIterator::SpiralTileIterator(TileIndex center, uint diameter) : this->SkipOutsideMap(); } -/** - * See SpiralTileSequence constructor for description. - */ +/** Create the iterator. @copydoc SpiralTileSequence::SpiralTileSequence(TileIndex, uint, uint, uint) */ SpiralTileIterator::SpiralTileIterator(TileIndex start_north, uint radius, uint w, uint h) : max_radius(radius), extent{w, h, w, h}, diff --git a/src/tilearea_type.h b/src/tilearea_type.h index 2ccc411391..9c242d0a95 100644 --- a/src/tilearea_type.h +++ b/src/tilearea_type.h @@ -137,16 +137,20 @@ public: /** * Move ourselves to the next tile in the rectangle on the map. + * @return Reference to this iterator. */ virtual TileIterator& operator ++() = 0; /** * Allocate a new iterator that is a copy of this one. + * @return A clone of this iterator. */ virtual std::unique_ptr Clone() const = 0; /** * Equality comparison. + * @param rhs The other iterator to compare to. + * @return \c true iff the tile of both iterators is the same. */ bool operator ==(const TileIterator &rhs) const { @@ -155,6 +159,8 @@ public: /** * Equality comparison. + * @param rhs The other iterator to compare to. + * @return \c true iff the tile of both iterators is the same. */ bool operator ==(const TileIndex &rhs) const { @@ -192,6 +198,7 @@ public: /** * Move ourselves to the next tile in the rectangle on the map. + * @return Reference to this iterator. */ inline TileIterator& operator ++() override { @@ -303,6 +310,7 @@ private: /** * Test whether the iterator reached the end. + * @return \c true iff the end of the iteration is reached. */ bool IsEnd() const { diff --git a/src/timer/timer_manager.h b/src/timer/timer_manager.h index f9bd890ae9..b54bc7f758 100644 --- a/src/timer/timer_manager.h +++ b/src/timer/timer_manager.h @@ -111,7 +111,10 @@ private: } }; - /** Singleton list, to store all the active timers. */ + /** + * Singleton list, to store all the active timers. + * @return The set of timers. + */ static std::set *, base_timer_sorter> &GetTimers() { static std::set *, base_timer_sorter> timers;