Standardize Doxygen documentation (#6885)

cockatrice/src/game_graphics/board/abstract_graphics_item.h

@@ -1,8 +1,8 @@
 /**
  * @file abstract_graphics_item.h
  * @ingroup GameGraphics
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef ABSTRACTGRAPHICSITEM_H
 #define ABSTRACTGRAPHICSITEM_H

cockatrice/src/game_graphics/board/graphics_item_type.h

@@ -1,8 +1,8 @@
 /**
  * @file graphics_item_type.h
  * @ingroup GameGraphics
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_GRAPHICS_ITEM_TYPE_H
 #define COCKATRICE_GRAPHICS_ITEM_TYPE_H

cockatrice/src/game_graphics/zones/card_zone.h

@@ -40,9 +40,12 @@ protected:
     }
 public slots:
     bool showContextMenu(const QPoint &screenPos);
-    /// @brief Called when a card is added to this zone. Default: reparents card to this item.
-    /// Virtual so subclasses (e.g. SelectZone) can override parenting behavior — the Qt signal
-    /// connection in CardZone's constructor dispatches through the vtable.
+    /**
+     * @brief Called when a card is added to this zone. Default: reparents card to this item.
+     *
+     * Virtual so subclasses (e.g. SelectZone) can override parenting behavior — the Qt signal
+     * connection in CardZone's constructor dispatches through the vtable.
+     */
     virtual void onCardAdded(CardItem *addedCard);
 
 public:

cockatrice/src/game_graphics/zones/pile_zone.h

@@ -1,8 +1,8 @@
 /**
  * @file pile_zone.h
  * @ingroup GameGraphicsZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef PILEZONE_H
 #define PILEZONE_H

cockatrice/src/game_graphics/zones/select_zone.h

@@ -21,33 +21,41 @@ class SelectZone : public CardZone
 {
     Q_OBJECT
 public:
-    /// Finds the SelectZone that owns a card, regardless of whether the card is parented
-    /// to the zone directly or to its clip container. Returns nullptr if not in a SelectZone.
+    /**
+     * @brief Finds the SelectZone that owns a card, regardless of whether the card is parented
+     * to the zone directly or to its clip container. Returns nullptr if not in a SelectZone.
+     */
     static SelectZone *findOwningSelectZone(const QGraphicsItem *card);
 
     SelectZone(CardZoneLogic *logic, QGraphicsItem *parent = nullptr);
     ~SelectZone() override;
     void onCardAdded(CardItem *addedCard) override;
 
-    /// @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip
-    /// bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no
-    /// transform).
+    /**
+     * @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip
+     * bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no
+     * transform).
+     */
     void escapeClipForHover(QGraphicsItem *card);
-    /// @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already
-    /// reparented the card.
+    /**
+     * @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already
+     * reparented the card.
+     */
     void restoreClipAfterHover(QGraphicsItem *card);
 
 private:
     QPointF selectionOrigin;
     QSet<CardItem *> cardsInSelectionRect;
-    /// Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone).
-    /// Created by setupClipContainer(); null when no clip container is active.
+    /**
+     * @brief Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone).
+     * Created by setupClipContainer(); null when no clip container is active.
+     */
     QGraphicsRectItem *cardClipContainer = nullptr;
 
 protected:
     // -- Layout computation --
 
-    /// Parameters describing a vertical card stack's geometry.
+    /** @brief Parameters describing a vertical card stack's geometry. */
     struct StackLayoutParams
     {
         int cardCount;         ///< Number of cards in the stack
@@ -55,21 +63,23 @@ protected:
         qreal cardHeight;      ///< Height of a single card
         qreal desiredOffset;   ///< Preferred vertical offset between card tops
         qreal minOffset = 0.0; ///< Minimum offset to preserve (0 allows full compression)
-        /// When false (default), reserves full cardHeight for the bottom card, ensuring
-        /// all cards remain within zone bounds. When true, allows the bottom card to
-        /// partially overflow using sqrt-scaled allowance. Use with setupClipContainer()
-        /// for zones too short to fit a full card.
+        /**
+         * @brief When false (default), reserves full cardHeight for the bottom card, ensuring
+         * all cards remain within zone bounds. When true, allows the bottom card to
+         * partially overflow using sqrt-scaled allowance. Use with setupClipContainer()
+         * for zones too short to fit a full card.
+         */
         bool allowBottomOverflow = false;
     };
 
-    /// Result of computing a vertical stack layout.
+    /** @brief Result of computing a vertical stack layout. */
     struct ZoneLayout
     {
         qreal effectiveOffset; ///< Actual offset between card tops (may be compressed)
         qreal start;           ///< Y coordinate of the first card's top edge
     };
 
-    /// Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones.
+    /** @brief Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones. */
     static constexpr qreal MIN_CARD_VISIBLE = 10.0;
 
     /**
@@ -88,11 +98,13 @@ protected:
      */
     static ZoneLayout computeZoneLayout(const StackLayoutParams &params);
 
-    /// Builds StackLayoutParams from the current card list and zone geometry.
+    /** @brief Builds StackLayoutParams from the current card list and zone geometry. */
     StackLayoutParams buildStackParams(qreal minOffset = 0.0) const;
 
-    /// Computes the card index at a given y-coordinate within the zone's vertical layout.
-    /// Returns 0 if the zone has no cards or the offset is zero.
+    /**
+     * @brief Computes the card index at a given y-coordinate within the zone's vertical layout.
+     * Returns 0 if the zone has no cards or the offset is zero.
+     */
     int calcDropIndexFromY(qreal dropY, qreal minOffset = 0.0) const;
 
     /**
@@ -111,17 +123,21 @@ protected:
     // (e.g., zones too short to fit a full card). To enable: call setupClipContainer() in the
     // zone's constructor, and set allowBottomOverflow=true in layout params.
 
-    /// Restores any cards that were hover-escaped but whose hover state was not properly cleaned up.
-    /// Call at the start of reorganizeCards() in zones that use a clip container.
+    /**
+     * @brief Restores any cards that were hover-escaped but whose hover state was not properly cleaned up.
+     * Call at the start of reorganizeCards() in zones that use a clip container.
+     */
     void restoreStaleEscapedCards();
 
-    /// Creates a clip container child item that clips card overflow to zone bounds.
-    /// Cards entering this zone are reparented to this container by the onCardAdded override.
-    /// Disables zone-level child clipping; clipping is delegated to the container.
-    /// @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE)
+    /**
+     * @brief Creates a clip container child item that clips card overflow to zone bounds.
+     * Cards entering this zone are reparented to this container by the onCardAdded override.
+     * Disables zone-level child clipping; clipping is delegated to the container.
+     * @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE)
+     */
     void setupClipContainer(std::optional<qreal> zValue = std::nullopt);
 
-    /// Updates the clip container rect to match this zone's current boundingRect().
+    /** @brief Updates the clip container rect to match this zone's current boundingRect(). */
     void updateClipRect();
 
     void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override;

cockatrice/src/game_graphics/zones/stack_zone.h

@@ -20,7 +20,7 @@ private slots:
 
 public:
     StackZone(StackZoneLogic *_logic, int _zoneHeight, QGraphicsItem *parent);
-    /// @brief Resizes the stack zone height, e.g. when sharing vertical space with the command zone.
+    /** @brief Resizes the stack zone height, e.g. when sharing vertical space with the command zone. */
     void setHeight(qreal newHeight);
     void
     handleDropEvent(const QList<CardDragItem *> &dragItems, CardZoneLogic *startZone, const QPoint &dropPoint) override;

cockatrice/src/game_graphics/zones/table_zone.h

@@ -1,8 +1,8 @@
 /**
  * @file table_zone.h
  * @ingroup GameGraphicsZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef TABLEZONE_H
 #define TABLEZONE_H
@@ -11,13 +11,12 @@
 #include "../../game/zones/table_zone_logic.h"
 #include "select_zone.h"
 
-/*
- * TableZone is the grid based rect where CardItems may be placed.
- * It is the main play zone and can be customized with background images.
+/**
+ * @brief TableZone is the grid based rect where CardItems may be placed.
  *
- * TODO: Refactor methods to make more readable, extract some logic to
- * private methods (Im looking at you TableZone::reorganizeCards())
+ * It is the main play zone and can be customized with background images.
  */
+//! \todo Refactor methods to make more readable, extract logic to private methods (especially reorganizeCards()).
 class TableZone : public SelectZone
 {
     Q_OBJECT

cockatrice/src/game_graphics/zones/view_zone.h

@@ -1,8 +1,8 @@
 /**
  * @file view_zone.h
  * @ingroup GameGraphicsZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef ZONEVIEWERZONE_H
 #define ZONEVIEWERZONE_H

cockatrice/src/game_graphics/zones/view_zone_widget.h

@@ -1,8 +1,8 @@
 /**
  * @file view_zone_widget.h
  * @ingroup GameGraphicsZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 #ifndef ZONEVIEWWIDGET_H
 #define ZONEVIEWWIDGET_H