Codechange: document a few parameter and return types

src/vehicle.cpp

@@ -394,6 +394,8 @@ constexpr uint TILE_HASH_RES = 0;
 
 /**
  * Compute hash for 1D tile coordinate.
+ * @param p The value to 'hash'.
+ * @return The computed hash.
  */
 static inline uint GetTileHash1D(uint p)
 {
@@ -402,6 +404,8 @@ static inline uint GetTileHash1D(uint p)
 
 /**
  * Increment 1D hash to next bucket.
+ * @param h The value to increment the hash for.
+ * @return The incremented value.
  */
 static inline uint IncTileHash1D(uint h)
 {
@@ -410,6 +414,9 @@ static inline uint IncTileHash1D(uint h)
 
 /**
  * Compose two 1D hashes into 2D hash.
+ * @param hx The hash for the X-axis.
+ * @param hy The hash for the Y-axis.
+ * @return The composed hash.
  */
 static inline uint ComposeTileHash(uint hx, uint hy)
 {
@@ -418,6 +425,9 @@ static inline uint ComposeTileHash(uint hx, uint hy)
 
 /**
  * Compute hash for tile coordinate.
+ * @param x The X-coordinate.
+ * @param y The Y-coordinate.
+ * @return The hash of the tile coordinates.
  */
 static inline uint GetTileHash(uint x, uint y)
 {
@@ -429,6 +439,9 @@ static std::array<Vehicle *, TOTAL_TILE_HASH_SIZE> _vehicle_tile_hash{};
 /**
  * Iterator constructor.
  * Find first vehicle near (x, y).
+ * @param x The center X-coordinate.
+ * @param y The center Y-coordinate.
+ * @param max_dist The distance around the center to consider.
  */
 VehiclesNearTileXY::Iterator::Iterator(int32_t x, int32_t y, uint max_dist)
 {
@@ -496,6 +509,7 @@ void VehiclesNearTileXY::Iterator::SkipFalseMatches()
 /**
  * Iterator constructor.
  * Find first vehicle on tile.
+ * @param tile The tile to find the vehicles on.
  */
 VehiclesOnTile::Iterator::Iterator(TileIndex tile) : tile(tile)
 {
@@ -2482,7 +2496,8 @@ bool Vehicle::HasUnbunchingOrder() const
 
 /**
  * Check if the previous order is a depot unbunching order.
- * @return true Iff the previous order is a depot order with the unbunch flag.
+ * @param v The vehicle to consider.
+ * @return \c true iff the previous order is a depot order with the unbunch flag.
  */
 static bool PreviousOrderIsUnbunching(const Vehicle *v)
 {

src/vehicle_gui.cpp

@@ -1383,7 +1383,11 @@ uint ShowRefitOptionsList(int left, int right, int y, EngineID engine)
 	return DrawStringMultiLine(left, right, y, INT32_MAX, str);
 }
 
-/** Get the cargo subtype text from NewGRF for the vehicle details window. */
+/**
+ * Get the cargo subtype text from NewGRF for the vehicle details window.
+ * @param v The vehicle to get the text for.
+ * @return The text or STR_EMPTY.
+ */
 StringID GetCargoSubtypeText(const Vehicle *v)
 {
 	if (!EngInfo(v->engine_type)->callback_mask.Test(VehicleCallbackMask::CargoSuffix)) return STR_EMPTY;
@@ -2533,7 +2537,12 @@ struct VehicleDetailsWindow : Window {
 		}
 	}
 
-	/** Checks whether service interval is enabled for the vehicle. */
+	/**
+	 * Checks whether service interval is enabled for the vehicle.
+	 * @param vehicle_type The vehicle type class (train, road vehicle, ship, aircraft).
+	 * @param company_id The company to consider.
+	 * @return \c true iff service interval are enabled for the given vehicle type and company.
+	 */
 	static bool IsVehicleServiceIntervalEnabled(const VehicleType vehicle_type, CompanyID company_id)
 	{
 		if (_local_company != company_id) return false;
@@ -2942,7 +2951,11 @@ void StartStopVehicle(const Vehicle *v, bool texteffect)
 	Command<Commands::StartStopVehicle>::Post(_vehicle_msg_translation_table[VCT_CMD_START_STOP][v->type], texteffect ? CcStartStopVehicle : nullptr, v->tile, v->index, false);
 }
 
-/** Checks whether the vehicle may be refitted at the moment.*/
+/**
+ * Checks whether the vehicle may be refitted at the moment.
+ * @param v The vehicle to consider.
+ * @return \c true iff the vehicle may be refitted now.
+ */
 static bool IsVehicleRefittable(const Vehicle *v)
 {
 	if (!v->IsStoppedInDepot()) return false;

src/viewport.cpp

@@ -780,6 +780,7 @@ void EndSpriteCombine()
  * @param begin The begin of the interval.
  * @param end   The end of the interval.
  * @param check The value to check.
+ * @return \c true iff check is between begin and end, including both begin and end.
  */
 static bool IsInRangeInclusive(int begin, int end, int check)
 {
@@ -1587,13 +1588,10 @@ static void ViewportDrawTileSprites(const TileSpriteToDrawVector *tstdv)
 	}
 }
 
-/** This fallback sprite checker always exists. */
-static bool ViewportSortParentSpritesChecker()
-{
-	return true;
-}
-
-/** Sort parent sprites pointer array replicating the way original sorter did it. */
+/**
+ * Sort parent sprites pointer array replicating the way original sorter did it.
+ * @param psdv The sprites to sort.
+ */
 static void ViewportSortParentSprites(ParentSpriteToSortVector *psdv)
 {
 	if (psdv->size() < 2) return;
@@ -2829,7 +2827,10 @@ void VpStartPlaceSizing(TileIndex tile, ViewportPlaceMethod method, ViewportDrag
 	_special_mouse_mode = WSM_SIZING;
 }
 
-/** Drag over the map while holding the left mouse down. */
+/**
+ * Drag over the map while holding the left mouse down.
+ * @param process The chosen selection process.
+ */
 void VpStartDragging(ViewportDragDropSelectionProcess process)
 {
 	_thd.select_method = VPM_X_AND_Y;
@@ -3594,7 +3595,7 @@ static const ViewportSSCSS _vp_sprite_sorters[] = {
 #ifdef WITH_SSE
 	{ &ViewportSortParentSpritesSSE41Checker, &ViewportSortParentSpritesSSE41 },
 #endif
-	{ &ViewportSortParentSpritesChecker, &ViewportSortParentSprites }
+	{ []() { return true; /* Always available */ }, &ViewportSortParentSprites }
 };
 
 /** Choose the "best" sprite sorter and set _vp_sprite_sorter. */

src/viewport_type.h

@@ -65,6 +65,10 @@ struct TrackedViewportSign : ViewportSign {
 	/**
 	 * Update the position of the viewport sign.
 	 * Note that this function hides the base class function.
+	 * @param center The (preferred) center of the viewport sign.
+	 * @param top The new top of the sign.
+	 * @param str The string to show in the sign.
+	 * @param str_small The string to show when zoomed out. If the string is empty then the \a str is used.
 	 */
 	void UpdatePosition(int center, int top, std::string_view str, std::string_view str_small = {})
 	{

src/water_cmd.cpp

@@ -816,7 +816,10 @@ static void DrawSeaWater(TileIndex)
 	DrawGroundSprite(SPR_FLAT_WATER_TILE, PAL_NONE);
 }
 
-/** draw a canal styled water tile with dikes around */
+/**
+ * Draw a canal styled water tile with dikes around.
+ * @param tile The tile to draw as canal.
+ */
 static void DrawCanalWater(TileIndex tile)
 {
 	SpriteID image = SPR_FLAT_WATER_TILE;
@@ -854,7 +857,10 @@ static void DrawWaterTileStruct(const TileInfo *ti, std::span<const DrawTileSeqS
 	}
 }
 
-/** Draw a lock tile. */
+/**
+ * Draw a lock tile.
+ * @param ti The tile information of the lock tile.
+ */
 static void DrawWaterLock(const TileInfo *ti)
 {
 	LockPart part = GetLockPart(ti->tile);
@@ -893,7 +899,10 @@ static void DrawWaterLock(const TileInfo *ti)
 	DrawWaterTileStruct(ti, dts.GetSequence(), base, zoffs, PAL_NONE, CF_LOCKS);
 }
 
-/** Draw a ship depot tile. */
+/**
+ * Draw a ship depot tile.
+ * @param ti The tile information of the ship depot tile.
+ */
 static void DrawWaterDepot(const TileInfo *ti)
 {
 	DrawWaterClassGround(ti);
@@ -1125,7 +1134,7 @@ static void FloodVehicles(TileIndex tile)
 
 /**
  * Returns the behaviour of a tile during flooding.
- *
+ * @param tile The tile to get the behaviour for.
  * @return Behaviour of the tile
  */
 FloodingBehaviour GetFloodingBehaviour(TileIndex tile)
@@ -1166,6 +1175,7 @@ FloodingBehaviour GetFloodingBehaviour(TileIndex tile)
 
 /**
  * Floods a tile.
+ * @param target The tile to consider.
  */
 static void DoFloodTile(TileIndex target)
 {
@@ -1234,6 +1244,7 @@ static void DoFloodTile(TileIndex target)
 
 /**
  * Drys a tile up.
+ * @param tile The tile to consider.
  */
 static void DoDryUp(TileIndex tile)
 {

src/waypoint_cmd.cpp

@@ -148,6 +148,7 @@ extern CommandCost ClearTile_Station(TileIndex tile, DoCommandFlags flags);
  * @param tile the tile to check for suitability
  * @param axis the axis of the waypoint
  * @param waypoint Waypoint the waypoint to check for is already joined to. If we find another waypoint it can join to it will throw an error.
+ * @return The command cost, or rather error when something it wrong.
  */
 static CommandCost IsValidTileForWaypoint(TileIndex tile, Axis axis, StationID *waypoint)
 {

src/widget.cpp

@@ -64,6 +64,8 @@ static inline Dimension ScaleGUITrad(const Dimension &dim)
 /**
  * Scale sprite size for GUI.
  * Offset is ignored.
+ * @param sprid The sprite to get the size from.
+ * @return The scaled dimension of the sprite.
  */
 Dimension GetScaledSpriteSize(SpriteID sprid)
 {

src/widget_type.h

@@ -275,6 +275,7 @@ protected:
 /**
  * Get the horizontal sizing step.
  * @param sizing Type of resize being performed.
+ * @return Depending on the sizing type the resize or fill on the X-axis.
  */
 inline uint NWidgetBase::GetHorizontalStepSize(SizingType sizing) const
 {
@@ -284,6 +285,7 @@ inline uint NWidgetBase::GetHorizontalStepSize(SizingType sizing) const
 /**
  * Get the vertical sizing step.
  * @param sizing Type of resize being performed.
+ * @return Depending on the sizing type the resize or fill on the Y-axis.
  */
 inline uint NWidgetBase::GetVerticalStepSize(SizingType sizing) const
 {
@@ -455,7 +457,10 @@ inline void NWidgetCore::SetLowered(bool lowered)
 	lowered ? this->disp_flags.Set(NWidgetDisplayFlag::Lowered) : this->disp_flags.Reset(NWidgetDisplayFlag::Lowered);
 }
 
-/** Return whether the widget is lowered. */
+/**
+ * Return whether the widget is lowered.
+ * @return \c true iff the widget is lowered.
+ */
 inline bool NWidgetCore::IsLowered() const
 {
 	return this->disp_flags.Test(NWidgetDisplayFlag::Lowered);
@@ -470,7 +475,10 @@ inline void NWidgetCore::SetDisabled(bool disabled)
 	this->disp_flags = disabled ? this->disp_flags.Set(NWidgetDisplayFlag::Disabled) : this->disp_flags.Reset(NWidgetDisplayFlag::Disabled);
 }
 
-/** Return whether the widget is disabled. */
+/**
+ * Return whether the widget is disabled.
+ * @return \c true iff the widget is disabled.
+ */
 inline bool NWidgetCore::IsDisabled() const
 {
 	return this->disp_flags.Test(NWidgetDisplayFlag::Disabled);
@@ -492,7 +500,10 @@ public:
 	void Draw(const Window *w) override;
 	NWidgetCore *GetWidgetFromPos(int x, int y) override;
 
-	/** Return whether the container is empty. */
+	/**
+	 * Return whether the container is empty.
+	 * @return \c true iff this container has no children.
+	 */
 	inline bool IsEmpty() { return this->children.empty(); }
 
 	NWidgetBase *GetWidgetOfType(WidgetType tp) override;
@@ -1153,6 +1164,7 @@ struct NWidgetPart {
  * Widget part function for setting the resize step.
  * @param dx Horizontal resize step. 0 means no horizontal resizing.
  * @param dy Vertical resize step. 0 means no vertical resizing.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetResize(int16_t dx, int16_t dy)
@@ -1164,6 +1176,7 @@ constexpr NWidgetPart SetResize(int16_t dx, int16_t dy)
  * Widget part function for setting the minimal size.
  * @param x Horizontal minimal size.
  * @param y Vertical minimal size.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetMinimalSize(int16_t x, int16_t y)
@@ -1173,6 +1186,7 @@ constexpr NWidgetPart SetMinimalSize(int16_t x, int16_t y)
 
 /**
  * Widget part function to setting the minimal size for a toolbar spacer.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetToolbarSpacerMinimalSize()
@@ -1183,6 +1197,7 @@ constexpr NWidgetPart SetToolbarSpacerMinimalSize()
 /**
  * Widget part function to setting the minimal size for a toolbar button.
  * @param width Width of button, measured in multiples of the standard toolbar button size.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetToolbarMinimalSize(int width)
@@ -1195,6 +1210,7 @@ constexpr NWidgetPart SetToolbarMinimalSize(int width)
  * @param lines   Number of text lines.
  * @param spacing Extra spacing required.
  * @param size    Font size of text.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetMinimalTextLines(uint8_t lines, uint8_t spacing, FontSize size = FS_NORMAL)
@@ -1206,6 +1222,7 @@ constexpr NWidgetPart SetMinimalTextLines(uint8_t lines, uint8_t spacing, FontSi
  * Widget part function for setting the text style.
  * @param colour Colour to draw string within widget.
  * @param size Font size to draw string within widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetTextStyle(TextColour colour, FontSize size = FS_NORMAL)
@@ -1216,6 +1233,7 @@ constexpr NWidgetPart SetTextStyle(TextColour colour, FontSize size = FS_NORMAL)
 /**
  * Widget part function for setting the alignment of text/images.
  * @param align  Alignment of text/image within widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetAlignment(StringAlignment align)
@@ -1227,6 +1245,7 @@ constexpr NWidgetPart SetAlignment(StringAlignment align)
  * Widget part function for setting filling.
  * @param fill_x Horizontal filling step from minimal size.
  * @param fill_y Vertical filling step from minimal size.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetFill(uint16_t fill_x, uint16_t fill_y)
@@ -1237,6 +1256,7 @@ constexpr NWidgetPart SetFill(uint16_t fill_x, uint16_t fill_y)
 /**
  * Widget part function for denoting the end of a container
  * (horizontal, vertical, WWT_FRAME, WWT_INSET, or WWT_PANEL).
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart EndContainer()
@@ -1248,6 +1268,7 @@ constexpr NWidgetPart EndContainer()
  * Widget part function for setting the string and tooltip.
  * @param string String of the widget.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetStringTip(StringID string, StringID tip = {})
@@ -1259,6 +1280,7 @@ constexpr NWidgetPart SetStringTip(StringID string, StringID tip = {})
  * Widget part function for setting the sprite and tooltip.
  * @param sprite Sprite of the widget.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetSpriteTip(SpriteID sprite, StringID tip = {})
@@ -1271,6 +1293,7 @@ constexpr NWidgetPart SetSpriteTip(SpriteID sprite, StringID tip = {})
  * @param sprite Sprite of the widget.
  * @param string String of the widget.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetSpriteStringTip(SpriteID sprite, StringID string, StringID tip = {})
@@ -1282,6 +1305,7 @@ constexpr NWidgetPart SetSpriteStringTip(SpriteID sprite, StringID string, Strin
  * Widget part function for setting the arrow widget type and tooltip.
  * @param widget_type Type of the widget to draw.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetArrowWidgetTypeTip(ArrowWidgetValues widget_type, StringID tip = {})
@@ -1293,6 +1317,7 @@ constexpr NWidgetPart SetArrowWidgetTypeTip(ArrowWidgetValues widget_type, Strin
  * Widget part function for setting the resize widget type and tooltip.
  * @param widget_type Type of the widget to draw.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetResizeWidgetTypeTip(ResizeWidgetValues widget_type, StringID tip)
@@ -1304,6 +1329,7 @@ constexpr NWidgetPart SetResizeWidgetTypeTip(ResizeWidgetValues widget_type, Str
  * Widget part function for setting the alternate colour and tooltip.
  * @param colour Alternate colour of the widget.
  * @param tip Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetAlternateColourTip(Colours colour, StringID tip)
@@ -1316,6 +1342,7 @@ constexpr NWidgetPart SetAlternateColourTip(Colours colour, StringID tip)
  * @param cols Number of columns. \c 0 means to use draw columns with width according to the resize step size.
  * @param rows Number of rows. \c 0 means to use draw rows with height according to the resize step size.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetMatrixDataTip(uint32_t cols, uint32_t rows, StringID tip = {})
@@ -1326,6 +1353,7 @@ constexpr NWidgetPart SetMatrixDataTip(uint32_t cols, uint32_t rows, StringID ti
 /**
  * Widget part function for setting tooltip and clearing the widget data.
  * @param tip  Tooltip of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetToolTip(StringID tip)
@@ -1340,6 +1368,7 @@ constexpr NWidgetPart SetToolTip(StringID tip)
  * @param right The padding right of the widget.
  * @param bottom The padding below the widget.
  * @param left The padding left of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPadding(uint8_t top, uint8_t right, uint8_t bottom, uint8_t left)
@@ -1351,6 +1380,7 @@ constexpr NWidgetPart SetPadding(uint8_t top, uint8_t right, uint8_t bottom, uin
  * Widget part function for setting additional space around a widget.
  * @param horizontal The padding on either side of the widget.
  * @param vertical The padding above and below the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPadding(uint8_t horizontal, uint8_t vertical)
@@ -1361,6 +1391,7 @@ constexpr NWidgetPart SetPadding(uint8_t horizontal, uint8_t vertical)
 /**
  * Widget part function for setting additional space around a widget.
  * @param padding The padding around the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPadding(const RectPadding &padding)
@@ -1371,6 +1402,7 @@ constexpr NWidgetPart SetPadding(const RectPadding &padding)
 /**
  * Widget part function for setting a padding.
  * @param padding The padding to use for all directions.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPadding(uint8_t padding)
@@ -1383,6 +1415,7 @@ constexpr NWidgetPart SetPadding(uint8_t padding)
  * @param pre The amount of space before the first widget.
  * @param inter The amount of space between widgets.
  * @param post The amount of space after the last widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPIP(uint8_t pre, uint8_t inter, uint8_t post)
@@ -1395,6 +1428,7 @@ constexpr NWidgetPart SetPIP(uint8_t pre, uint8_t inter, uint8_t post)
  * @param ratio_pre The ratio of space before the first widget.
  * @param ratio_inter The ratio of space between widgets.
  * @param ratio_post The ratio of space after the last widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetPIPRatio(uint8_t ratio_pre, uint8_t ratio_inter, uint8_t ratio_post)
@@ -1407,6 +1441,7 @@ constexpr NWidgetPart SetPIPRatio(uint8_t ratio_pre, uint8_t ratio_inter, uint8_
  * The scrollbar is controlled when using the mousewheel on the widget.
  * Multiple widgets can refer to the same scrollbar to make the mousewheel work in all of them.
  * @param index Widget index of the scrollbar.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetScrollbar(WidgetID index)
@@ -1418,6 +1453,7 @@ constexpr NWidgetPart SetScrollbar(WidgetID index)
  * Widget part function for setting the aspect ratio.
  * @param ratio Desired aspect ratio, or 0 for none.
  * @param flags Dimensions which should be resized.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart SetAspect(float ratio, AspectFlags flags = AspectFlag::ResizeX)
@@ -1430,6 +1466,7 @@ constexpr NWidgetPart SetAspect(float ratio, AspectFlags flags = AspectFlag::Res
  * @param tp  Type of the new nested widget.
  * @param col Colour of the new widget.
  * @param idx Index of the widget.
+ * @return The created widget part.
  * @note with #WWT_PANEL, #WWT_FRAME, #WWT_INSET, a new container is started.
  *       Child widgets must have a index bigger than the parent index.
  * @ingroup NestedWidgetParts
@@ -1444,6 +1481,7 @@ constexpr NWidgetPart NWidget(WidgetType tp, Colours col, WidgetID idx = INVALID
  * @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).
  * @param idx Optional identifier of the widget.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart NWidget(WidgetType tp, NWidContainerFlags cont_flags = {}, WidgetID idx = INVALID_WIDGET)
@@ -1454,6 +1492,7 @@ constexpr NWidgetPart NWidget(WidgetType tp, NWidContainerFlags cont_flags = {},
 /**
  * Obtain a nested widget (sub)tree from an external source.
  * @param func_ptr Pointer to function that returns the tree.
+ * @return The created widget part.
  * @ingroup NestedWidgetParts
  */
 constexpr NWidgetPart NWidgetFunction(NWidgetFunctionType *func_ptr)

src/window.cpp

@@ -104,7 +104,19 @@ std::vector<WindowDesc*> *_window_descs = nullptr;
 /** Config file to store WindowDesc */
 std::string _windows_file;
 
-/** Window description constructor. */
+/**
+ * Window description constructor.
+ * @param def_pos The default location to open the window.
+ * @param ini_key The key for storing settings of this window in the savegame.
+ * @param def_width_trad The default width without scaling.
+ * @param def_height_trad The default height without scaling.
+ * @param window_class The class of windows.
+ * @param parent_class The window class of our parents.
+ * @param flags Arbitrary flags to describe certain behaviour of the window.
+ * @param nwid_parts The widgets of the window.
+ * @param hotkeys The optional hotkeys.
+ * @param location The source code location where the window is instantiated.
+ */
 WindowDesc::WindowDesc(WindowPosition def_pos, std::string_view ini_key, int16_t def_width_trad, int16_t def_height_trad,
 			WindowClass window_class, WindowClass parent_class, WindowDefaultFlags flags,
 			const std::span<const NWidgetPart> nwid_parts, HotkeyList *hotkeys,
@@ -2803,7 +2815,7 @@ static constexpr int MAX_OFFSET_HOVER = 5; ///< Maximum mouse movement before st
 
 extern EventState VpHandlePlaceSizingDrag();
 
-const std::chrono::milliseconds TIME_BETWEEN_DOUBLE_CLICK(500); ///< Time between 2 left clicks before it becoming a double click.
+const std::chrono::milliseconds TIME_BETWEEN_DOUBLE_CLICK{500}; ///< Time between 2 left clicks before it becoming a double click.
 
 static void ScrollMainViewport(int x, int y)
 {
@@ -3090,6 +3102,7 @@ bool CanContinueRealtimeTick()
 
 /**
  * Dispatch OnRealtimeTick event over all windows
+ * @param delta_ms The number of milliseconds since the last call.
  */
 void CallWindowRealtimeTickEvent(uint delta_ms)
 {
@@ -3609,6 +3622,7 @@ void RelocateAllWindows(int neww, int newh)
 /**
  * Hide the window and all its child windows, and mark them for a later deletion.
  * Always call ResetObjectToPlace() when closing a PickerWindow.
+ * @copydoc Window::Close
  */
 void PickerWindowBase::Close([[maybe_unused]] int data)
 {

src/window_gui.h

@@ -556,7 +556,10 @@ public:
 	void SetDirty() const;
 	void ReInit(int rx = 0, int ry = 0, bool reposition = false);
 
-	/** Is window shaded currently? */
+	/**
+	 * Is window shaded currently?
+	 * @return \c true iff the window supports shading and is shaded.
+	 */
 	inline bool IsShaded() const
 	{
 		return this->shade_select != nullptr && this->shade_select->shown_plane == SZSP_HORIZONTAL;
@@ -748,6 +751,7 @@ public:
 
 	/**
 	 * Called periodically.
+	 * @param delta_ms The number of milliseconds since the last call.
 	 */
 	virtual void OnRealtimeTick([[maybe_unused]] uint delta_ms) {}
 
@@ -967,7 +971,7 @@ inline NWID *Window::GetWidget(WidgetID widnum)
 	return nwid;
 }
 
-/** Specialized case of #Window::GetWidget for the nested widget base class. */
+/** Specialized case of #Window::GetWidget for the nested widget base class. @copydoc Window::GetWidget */
 template <>
 inline const NWidgetBase *Window::GetWidget<NWidgetBase>(WidgetID widnum) const
 {
@@ -1000,7 +1004,7 @@ public:
 		this->parent = parent;
 	}
 
-	void Close([[maybe_unused]] int data = 0) override;
+	void Close(int data = 0) override;
 };
 
 Window *BringWindowToFrontById(WindowClass cls, WindowNumber number);