Codechange: document parameters and return types

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<DiagDirection, SIG_TBD_SIZE> _tbdset("_tbdset");    ///< set of
 static SmallSet<DiagDirection, SIG_GLOB_SIZE> _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;

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)
 {

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)

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)
 	{

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

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<SocialIntegrationPlugin *> 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);
 

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<uint8_t>(this->origin.z) != 0x80;

src/spriteloader/sprite_file.cpp

@@ -16,6 +16,7 @@ extern const std::array<uint8_t, 8> _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)

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

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;

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)
 {

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; }
 

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()
 {

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
 	{

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
 {

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<const char> str)
 {

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
 {

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<StringParameter> args)
 {

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<StringParameter> 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());

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()
 {

src/textfile_gui.cpp

@@ -847,6 +847,8 @@ static std::vector<char> Xunzip(std::span<char> 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)
 {

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<OrthogonalTileIterator>(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},

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<TileIterator> 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
 	{

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<BaseTimer<TTimerType> *, base_timer_sorter> &GetTimers()
 	{
 		static std::set<BaseTimer<TTimerType> *, base_timer_sorter> timers;