📝 Fixes Doxygen warnings (#4904)

Source/DiabloUI/ui_item.h

@@ -241,6 +241,8 @@ class UiArtText : public UiItemBase {
 	 * @param text Pointer to the first character of a c-string
 	 * @param rect screen region defining the area to draw the text
 	 * @param flags UiFlags controlling color/alignment/size
+	 * @param spacing Spacing between characters
+	 * @param lineHeight Vertical distance between text lines
 	 */
 	UiArtText(const char *text, SDL_Rect rect, UiFlags flags = UiFlags::None, int spacing = 1, int lineHeight = -1)
 	    : UiItemBase(UiType::ArtText, rect, flags)
@@ -255,6 +257,8 @@ class UiArtText : public UiItemBase {
 	 * @param ptext Pointer to a c-string (pointer to a pointer to the first character)
 	 * @param rect screen region defining the area to draw the text
 	 * @param flags UiFlags controlling color/alignment/size
+	 * @param spacing Spacing between characters
+	 * @param lineHeight Vertical distance between text lines
 	 */
 	UiArtText(const char **ptext, SDL_Rect rect, UiFlags flags = UiFlags::None, int spacing = 1, int lineHeight = -1)
 	    : UiItemBase(UiType::ArtText, rect, flags)

Source/capture.cpp

@@ -111,7 +111,9 @@ BYTE *CaptureEnc(BYTE *src, BYTE *dst, int width)
 
 /**
  * @brief Write the pixel data to the PCX file
- * @param buf Buffer
+ *
+ * @param buf Pixel data
+ * @param out File stream for the PCX file.
  * @return True if successful, else false
  */
 bool CapturePix(const Surface &buf, std::ofstream *out)

Source/controls/README.md

@@ -1,4 +1,4 @@
-#Controls handling
+# Controls handling
 
 DevilutionX supports mouse & keyboard and gamepad input.
 

Source/controls/plrctrls.cpp

@@ -101,7 +101,7 @@ int GetRotaryDistance(Point destination)
 
 /**
  * @brief Get the best case walking steps to coordinates
- * @param Position Tile coordinates
+ * @param position Tile coordinates
  */
 int GetMinDistance(Point position)
 {

Source/engine.cpp

@@ -163,23 +163,6 @@ void DrawHalfTransparentRectTo(const Surface &out, int sx, int sy, int width, in
 	DrawHalfTransparentBlendedRectTo(out, sx, sy, width, height);
 }
 
-/**
- * @brief Returns the direction a vector from p1(x1, y1) to p2(x2, y2) is pointing to.
- *
- *      W    SW     S
- *            ^
- *            |
- *     NW ----+---> SE
- *            |
- *            |
- *      N    NE     E
- *
- * @param x1 the x coordinate of p1
- * @param y1 the y coordinate of p1
- * @param x2 the x coordinate of p2
- * @param y2 the y coordinate of p2
- * @return the direction of the p1->p2 vector
- */
 Direction GetDirection(Point start, Point destination)
 {
 	Direction md;

Source/engine/animationinfo.h

@@ -95,7 +95,6 @@ class AnimationInfo {
 	/**
 	 * @brief Process the Animation for a game tick (for example advances the frame)
 	 * @param reverseAnimation Play the animation backwards (for example is used for "unseen" monster fading)
-	 * @param dontProgressAnimation Increase tickCounterOfCurrentFrame but don't change currentFrame
 	 */
 	void processAnimation(bool reverseAnimation = false);
 

Source/engine/render/cel_render.cpp

@@ -546,6 +546,7 @@ void RenderCelOutline(const Surface &out, Point position, const byte *src, std::
  * @param position Target buffer coordinate
  * @param pRLEBytes CEL pixel stream (run-length encoded)
  * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite in pixels
  */
 void CelBlitSafeTo(const Surface &out, Point position, const byte *pRLEBytes, int nDataSize, int nWidth)
 {
@@ -555,10 +556,11 @@ void CelBlitSafeTo(const Surface &out, Point position, const byte *pRLEBytes, in
 
 /**
  * @brief Same as CelBlitLightSafe, with blended transparency applied
- * @param out The output buffer
+ * @param out Target buffer
+ * @param position Target buffer coordinate
  * @param pRLEBytes CEL pixel stream (run-length encoded)
  * @param nDataSize Size of CEL in bytes
- * @param nWidth Width of sprite
+ * @param nWidth Width of sprite in pixels
  * @param tbl Palette translation table
  */
 void CelBlitLightBlendedSafeTo(const Surface &out, Point position, const byte *pRLEBytes, int nDataSize, int nWidth, const uint8_t *tbl)
@@ -583,6 +585,7 @@ void CelBlitLightBlendedSafeTo(const Surface &out, Point position, const byte *p
  * @param position Target buffer coordinate
  * @param pRLEBytes CEL pixel stream (run-length encoded)
  * @param nDataSize Size of CEL in bytes
+ * @param nWidth Width of sprite in pixels
  * @param tbl Palette translation table
  */
 void CelBlitLightSafeTo(const Surface &out, Point position, const byte *pRLEBytes, int nDataSize, int nWidth, uint8_t *tbl)

Source/engine/render/cel_render.hpp

@@ -38,7 +38,7 @@ void CelApplyTrans(byte *p, const std::array<uint8_t, 256> &translation);
 void CelDrawTo(const Surface &out, Point position, CelSprite cel, int frame);
 
 /**
- * @briefBlit CEL sprite to the given buffer, does not perform bounds-checking.
+ * @brief Blit CEL sprite to the given buffer, does not perform bounds-checking.
  * @param out Target buffer
  * @param position Coordinate in the target buffer coordinate
  * @param cel CEL sprite
@@ -61,6 +61,7 @@ void CelClippedDrawTo(const Surface &out, Point position, CelSprite cel, int fra
  * @param position Target buffer coordinate
  * @param cel CEL sprite
  * @param frame CEL frame number
+ * @param tbl Palette translation table
  */
 void CelDrawLightTo(const Surface &out, Point position, CelSprite cel, int frame, uint8_t *tbl);
 
@@ -106,7 +107,7 @@ void CelDrawItem(const Item &item, const Surface &out, Point position, CelSprite
  * @param out Target buffer
  * @param col Color index from current palette
  * @param position Target buffer coordinate
- * @param pCelBuff CEL buffer
+ * @param cel CEL sprite
  * @param frame CEL frame number
  * @param skipColorIndexZero If true, color in index 0 will be treated as transparent (these are typically used for shadows in sprites)
  */

Source/engine/render/cl2_render.hpp

@@ -27,8 +27,8 @@ void Cl2ApplyTrans(byte *p, const std::array<uint8_t, 256> &ttbl, int numFrames)
  * @param out Output buffer
  * @param sx Output buffer coordinate
  * @param sy Output buffer coordinate
- * @param pCelBuff CL2 buffer
- * @param nCel CL2 frame number
+ * @param cel CL2 buffer
+ * @param frame CL2 frame number
  */
 void Cl2Draw(const Surface &out, int sx, int sy, CelSprite cel, int frame);
 
@@ -38,8 +38,8 @@ void Cl2Draw(const Surface &out, int sx, int sy, CelSprite cel, int frame);
  * @param out Output buffer
  * @param sx Output buffer coordinate
  * @param sy Output buffer coordinate
- * @param pCelBuff CL2 buffer
- * @param nCel CL2 frame number
+ * @param cel CL2 buffer
+ * @param frame CL2 frame number
  */
 void Cl2DrawOutline(const Surface &out, uint8_t col, int sx, int sy, CelSprite cel, int frame);
 
@@ -48,9 +48,9 @@ void Cl2DrawOutline(const Surface &out, uint8_t col, int sx, int sy, CelSprite c
  * @param out Output buffer
  * @param sx Output buffer coordinate
  * @param sy Output buffer coordinate
- * @param pCelBuff CL2 buffer
- * @param nCel CL2 frame number
- * @param TRN to use
+ * @param cel CL2 buffer
+ * @param frame CL2 frame number
+ * @param trn TRN to use
  */
 void Cl2DrawTRN(const Surface &out, int sx, int sy, CelSprite cel, int frame, uint8_t *trn);
 
@@ -59,8 +59,8 @@ void Cl2DrawTRN(const Surface &out, int sx, int sy, CelSprite cel, int frame, ui
  * @param out Output buffer
  * @param sx Output buffer coordinate
  * @param sy Output buffer coordinate
- * @param pCelBuff CL2 buffer
- * @param nCel CL2 frame number
+ * @param cel CL2 buffer
+ * @param frame CL2 frame number
  */
 void Cl2DrawLight(const Surface &out, int sx, int sy, CelSprite cel, int frame);
 

Source/engine/render/scrollrt.cpp

@@ -309,7 +309,7 @@ void DrawCursor(const Surface &out)
 /**
  * @brief Render a missile sprite
  * @param out Output buffer
- * @param m Pointer to Missile struct
+ * @param missile Pointer to Missile struct
  * @param targetBufferPosition Output buffer coordinate
  * @param pre Is the sprite in the background
  */
@@ -359,7 +359,7 @@ void DrawMissile(const Surface &out, Point tilePosition, Point targetBufferPosit
  * @param out Output buffer
  * @param tilePosition dPiece coordinates
  * @param targetBufferPosition Output buffer coordinates
- * @param m Id of monster
+ * @param monster Monster reference
  */
 void DrawMonster(const Surface &out, Point tilePosition, Point targetBufferPosition, const Monster &monster)
 {
@@ -486,8 +486,9 @@ void DrawPlayerIconHelper(const Surface &out, missile_graphic_id missileGraphicI
 /**
  * @brief Helper for rendering player icons (Mana Shield and Reflect)
  * @param out Output buffer
+ * @param player Player reference
  * @param position Output buffer coordinates
- * @param lighting Should lighting be applied
+ * @param infraVision Should infravision be applied
  */
 void DrawPlayerIcons(const Surface &out, const Player &player, Point position, bool infraVision)
 {
@@ -500,6 +501,7 @@ void DrawPlayerIcons(const Surface &out, const Player &player, Point position, b
 /**
  * @brief Render a player sprite
  * @param out Output buffer
+ * @param player Player reference
  * @param tilePosition dPiece coordinates
  * @param targetBufferPosition Output buffer coordinates
  */
@@ -789,6 +791,7 @@ void DrawMonsterHelper(const Surface &out, Point tilePosition, Point targetBuffe
 /**
  * @brief Check if and how a player should be rendered
  * @param out Output buffer
+ * @param player Player reference
  * @param tilePosition dPiece coordinates
  * @param targetBufferPosition Output buffer coordinates
  */
@@ -1061,7 +1064,7 @@ int tileRows;
 
 /**
  * @brief Configure render and process screen rows
- * @param full_out Buffer to render to
+ * @param fullOut Buffer to render to
  * @param position Center of view in dPiece coordinate
  */
 void DrawGame(const Surface &fullOut, Point position)
@@ -1353,11 +1356,11 @@ void DoBlitScreen(Sint16 dwX, Sint16 dwY, Uint16 dwWdt, Uint16 dwHgt)
 /**
  * @brief Check render pipeline and blit individual screen parts
  * @param dwHgt Section of screen to update from top to bottom
- * @param draw_desc Render info box
- * @param draw_hp Render health bar
- * @param draw_mana Render mana bar
- * @param draw_sbar Render belt
- * @param draw_btn Render panel buttons
+ * @param drawDesc Render info box
+ * @param drawHp Render health bar
+ * @param drawMana Render mana bar
+ * @param drawSbar Render belt
+ * @param drawBtn Render panel buttons
  */
 void DrawMain(int dwHgt, bool drawDesc, bool drawHp, bool drawMana, bool drawSbar, bool drawBtn)
 {

Source/engine/render/scrollrt.h

@@ -50,6 +50,8 @@ void ClearCursor();
 /**
  * @brief Shifting the view area along the logical grid
  *        Note: this won't allow you to shift between even and odd rows
+ * @param x X offset
+ * @param y Y offset
  * @param horizontal Shift the screen left or right
  * @param vertical Shift the screen up or down
  */

Source/engine/render/text_render.hpp

@@ -143,6 +143,7 @@ int GetLineWidth(string_view text, GameFontTables size = GameFont12, int spacing
  * @brief Calculate pixel width of first line of text, respecting kerning
  * @param fmt An fmt::format string.
  * @param args Format arguments.
+ * @param argsLen Number of format arguments.
  * @param size Font size to use
  * @param spacing Extra spacing to add per character
  * @param charactersInLine Receives characters read until newline or terminator
@@ -210,12 +211,13 @@ inline void DrawString(const Surface &out, string_view text, const Point &positi
 /**
  * @brief Draws a line of text with different colors for certain parts of the text.
  *
- * @example DrawStringWithColors(out, "Press {} to start", {{"Ⓧ", UiFlags::ColorBlue}}, UiFlags::ColorWhite)
+ *     DrawStringWithColors(out, "Press {} to start", {{"Ⓧ", UiFlags::ColorBlue}}, UiFlags::ColorWhite)
  *
  * @param out Output buffer to draw the text on.
  * @param fmt An fmt::format string.
  * @param args Format arguments.
- * @param position Location of the top left corner of the string relative to the top left corner of the output buffer.
+ * @param argsLen Number of format arguments.
+ * @param rect Clipping region relative to the output buffer describing where to draw the text and when to wrap long lines.
  * @param flags A combination of UiFlags to describe font size, color, alignment, etc. See ui_items.h for available options
  * @param spacing Additional space to add between characters.
  *                This value may be adjusted if the flag UIS_FIT_SPACING is passed in the flags parameter.

Source/engine/surface.hpp

@@ -77,7 +77,7 @@ struct Surface {
 
 	/**
 	 * @brief Set the value of a single pixel if it is in bounds.
-	 * @param point Target buffer coordinate
+	 * @param position Target buffer coordinate
 	 * @param col Color index from current palette
 	 */
 	void SetPixel(Point position, std::uint8_t col) const

Source/engine/trn.hpp

@@ -1,5 +1,5 @@
 /**
- * @file trn.h
+ * @file trn.hpp
  *
  * Contains most of trn logic
  */

Source/inv.cpp

@@ -40,6 +40,8 @@ bool drawsbarflag;
 /**
  * Maps from inventory slot to screen position. The inventory slots are
  * arranged as follows:
+ *
+ * @code{.unparsed}
  *                          00 01
  *                          02 03   06
  *
@@ -55,6 +57,7 @@ bool drawsbarflag;
  *              55 56 57 58 59 60 61 62 63 64
  *
  * 65 66 67 68 69 70 71 72
+ * @endcode
  */
 const Point InvRect[] = {
 	// clang-format off
@@ -141,6 +144,7 @@ OptionalOwnedCelSprite pInvCels;
 
 /**
  * @brief Adds an item to a player's InvGrid array
+ * @param player The player reference
  * @param invGridIndex Item's position in InvGrid (this should be the item's topleft grid tile)
  * @param invListIndex The item's InvList index (it's expected this already has +1 added to it since InvGrid can't store a 0 index)
  * @param itemSize Size of item

Source/inv.h

@@ -38,7 +38,7 @@ enum inv_item : int8_t {
 
 /**
  * identifiers for each of the inventory squares
- * @see #InvRect
+ * @see InvRect
  */
 enum inv_xy_slot : uint8_t {
 	// clang-format off
@@ -130,7 +130,7 @@ bool AutoEquipEnabled(const Player &player, const Item &item);
 /**
  * @brief Automatically attempts to equip the specified item in the most appropriate location in the player's body.
  * @note On success, this will broadcast an equipment_change event to let other players know about the equipment change.
- * @param playerId The player number whose inventory will be checked for compatibility with the item.
+ * @param player The player whose inventory will be checked for compatibility with the item.
  * @param item The item to equip.
  * @param persistItem Indicates whether or not the item should be persisted in the player's body. Pass 'False' to check
  * whether the player can equip the item but you don't want the item to actually be equipped. 'True' by default.
@@ -141,6 +141,7 @@ bool AutoEquip(Player &player, const Item &item, bool persistItem = true);
 /**
  * @brief Checks whether the given item can be placed on the specified player's inventory.
  * If 'persistItem' is 'True', the item is also placed in the inventory.
+ * @param player The player whose inventory will be checked.
  * @param item The item to be checked.
  * @param persistItem Pass 'True' to actually place the item in the inventory. The default is 'False'.
  * @return 'True' in case the item can be placed on the player's inventory and 'False' otherwise.
@@ -150,6 +151,7 @@ bool AutoPlaceItemInInventory(Player &player, const Item &item, bool persistItem
 /**
  * @brief Checks whether the given item can be placed on the specified player's inventory slot.
  * If 'persistItem' is 'True', the item is also placed in the inventory slot.
+ * @param player The player whose inventory will be checked.
  * @param slotIndex The 0-based index of the slot to put the item on.
  * @param item The item to be checked.
  * @param persistItem Pass 'True' to actually place the item in the inventory slot. The default is 'False'.
@@ -206,7 +208,7 @@ void AutoGetItem(Player &player, Item *itemPointer, int ii);
  * @brief Searches for a dropped item with the same type/createInfo/seed
  * @param iseed The value used to initialise the RNG when generating the item
  * @param idx The overarching type of the target item
- * @param createInfo Flags used to describe the specific subtype of the target item
+ * @param ci Flags used to describe the specific subtype of the target item
  * @return An index into ActiveItems or -1 if no matching item was found
  */
 int FindGetItem(int32_t iseed, _item_indexes idx, uint16_t ci);

Source/items.h

@@ -462,7 +462,7 @@ int GetGoldCursor(int value);
 
 /**
  * @brief Update the gold cursor on the given gold item
- * @param h The item to update
+ * @param gold The item to update
  */
 void SetPlrHandGoldCurs(Item &gold);
 void CreatePlrItems(Player &player);

Source/levels/gendung.h

@@ -284,6 +284,7 @@ struct Miniset {
 	uint8_t replace[6][6];
 
 	/**
+	 * @param position Coordinates of the dungeon tile to check
 	 * @param respectProtected Match bug from Crypt levels
 	 */
 	bool matches(Point position, bool respectProtected = true) const
@@ -325,6 +326,7 @@ void LoadTransparency(const uint16_t *dunData);
 void LoadDungeonBase(const char *path, Point spawn, int floorId, int dirtId);
 void Make_SetPC(Rectangle area);
 /**
+ * @param miniset The miniset to place
  * @param tries Tiles to try, 1600 will scan the full map
  * @param drlg1Quirk Match buggy behaviour of Diablo's Cathedral
  */

Source/levels/town.cpp

@@ -56,7 +56,6 @@ void FillSector(const char *path, int xi, int yy)
 
 /**
  * @brief Load a tile in to dPiece
- * @param megas Map from mega tiles to macro tiles
  * @param xx upper left destination
  * @param yy upper left destination
  * @param t tile id