Fix stale documentation and align doc comments with CONTRIBUTING guidelines

cockatrice/src/game/board/counter_state.h

@@ -40,16 +40,19 @@ public:
     {
         return value;
     }
+    /** @brief Returns whether this counter is active (visible and modifiable). */
     bool isActive() const
     {
         return active;
     }
 
     void setValue(int newValue);
+    /** @brief Sets the active (visible) state and emits activeChanged if it changed. */
     void setActive(bool newActive);
 
 signals:
     void valueChanged(int oldValue, int newValue);
+    /** @brief Emitted when the counter's active state changes. */
     void activeChanged(bool newActive);
 
 private:
@@ -58,7 +61,7 @@ private:
     QColor color;
     int radius;
     int value;
-    bool active;
+    bool active; ///< Inactive counters are hidden; server rejects modification attempts
 };
 
 #endif // COCKATRICE_COUNTER_STATE_H

cockatrice/src/game/player/player_actions.h

@@ -228,6 +228,7 @@ public slots:
     void cardMenuAction(QList<CardItem *> selectedCards, CardMenuActionType type);
 
 private:
+    /** @brief Sends an increment command for the specified counter. */
     void sendIncCounter(int counterId, int delta);
 
     PlayerLogic *player;
@@ -258,6 +259,8 @@ private:
 
     /**
      * @brief Builds the move command for playing a card, returning the prepared (unsent) PendingCommand.
+     * @param card The card to play
+     * @param faceDown Whether to play the card face-down
      * @return The prepared command, or nullptr if the card cannot be played.
      */
     PendingCommand *prepareCardMove(CardItem *card, bool faceDown);

cockatrice/src/game/player/player_event_handler.h

@@ -156,7 +156,7 @@ public:
     /// Set a player-level counter value.
     void eventSetCounter(const Event_SetCounter &event);
 
-    /// Show or hide a player-level counter without deleting it.
+    /** @brief Show or hide a player-level counter without deleting it. */
     void eventSetCounterActive(const Event_SetCounterActive &event);
 
     /// Delete a player-level counter.

cockatrice/src/game/player/player_logic.h

@@ -89,6 +89,7 @@ signals:
     void arrowDeleteRequested(int creatorId, int arrowId);
     void arrowDeleted(int creatorId, int arrowId);
     void arrowsClearedLocally(); // fires on clear() and processPlayerInfo
+    /** @brief Emitted when server command zone support is detected or lost (e.g. on game join or reconnect). */
     void commandZoneSupportChanged(bool hasCommandZone);
 
 public slots:

cockatrice/src/game_graphics/board/abstract_counter.h

@@ -3,7 +3,6 @@
  * @ingroup GameGraphicsPlayers
  * @brief Abstract base for player counters displayed on the game board.
  */
-//! \todo Document this file.
 
 #ifndef COUNTER_H
 #define COUNTER_H
@@ -21,6 +20,7 @@ class QKeyEvent;
 class QMenu;
 class QString;
 
+//! \todo Document AbstractCounter class members.
 class AbstractCounter : public QObject, public QGraphicsItem, public AbstractPlayerComponent
 {
     Q_OBJECT
@@ -65,8 +65,11 @@ public:
 
     /**
      * @brief Sets the counter value and triggers a visual update.
+     *
      * Virtual to allow subclass display customization (e.g., CommanderTaxCounter tooltip updates).
      * Overflow protection is handled server-side, not in client counter classes.
+     *
+     * @param _value The new counter value
      */
     virtual void setValue(int _value);
     void setShortcutsActive() override;
@@ -120,7 +123,7 @@ public:
     virtual void setActive(bool _active);
 
 private:
-    bool active = true;
+    bool active = true; ///< Whether the counter is shown and modifiable
 };
 
 class AbstractCounterDialog : public QInputDialog

cockatrice/src/game_graphics/board/commander_tax_counter.h

@@ -28,9 +28,10 @@ constexpr int TAX_COUNTER_MARGIN = 2;
  * @class CommanderTaxCounter
  * @brief Counter for tracking commander tax in Commander format.
  *
- * Displays cumulative cost increase for casting a commander. The counter
- * is manually adjusted by the player to track their commander tax. Values
- * are clamped to >= 0.
+ * Displays the number of times the commander has been cast from the command
+ * zone. Can be adjusted manually via +1/-1 menu actions, or automatically
+ * incremented when using "Play and Increase Tax" on an accepted cast from
+ * the command zone. Values are clamped to >= 0.
  *
  * Appearance: square with rounded corners, semi-transparent background,
  * positioned at top-left of command zone.
@@ -48,7 +49,7 @@ class CommanderTaxCounter : public AbstractCounter
 {
     Q_OBJECT
 private:
-    int size;
+    int size; ///< Width and height of the counter in pixels
 
 public:
     /**

cockatrice/src/game_graphics/board/translate_counter_name.cpp

@@ -1,5 +1,7 @@
 #include "translate_counter_name.h"
 
+#include <libcockatrice/utility/counter_ids.h>
+
 const QMap<QString, QString> TranslateCounterName::translated = {
     {"life", QT_TRANSLATE_NOOP("TranslateCounterName", "Life")},
     {"w", QT_TRANSLATE_NOOP("TranslateCounterName", "White")},
@@ -9,5 +11,5 @@ const QMap<QString, QString> TranslateCounterName::translated = {
     {"g", QT_TRANSLATE_NOOP("TranslateCounterName", "Green")},
     {"x", QT_TRANSLATE_NOOP("TranslateCounterName", "Colorless")},
     {"storm", QT_TRANSLATE_NOOP("TranslateCounterName", "Other")},
-    {"commander_tax_counter", QT_TRANSLATE_NOOP("TranslateCounterName", "Commander Tax")},
-    {"partner_tax_counter", QT_TRANSLATE_NOOP("TranslateCounterName", "Partner Tax")}};
+    {CounterNames::CommanderTax, QT_TRANSLATE_NOOP("TranslateCounterName", "Commander Tax")},
+    {CounterNames::PartnerTax, QT_TRANSLATE_NOOP("TranslateCounterName", "Partner Tax")}};

cockatrice/src/game_graphics/player/menu/card_menu.h

@@ -32,9 +32,8 @@ public:
     QMenu *mCardCounters;
 
     QAction *aPlay, *aPlayFacedown;
-    QAction *
-        aPlayAndIncreaseTax; ///< Plays card and increments the primary commander tax counter (CounterIds::CommanderTax)
-    QAction *aPlayAndIncreasePartnerTax;
+    /** @brief Play actions that also increment the corresponding tax counter. */
+    QAction *aPlayAndIncreaseTax, *aPlayAndIncreasePartnerTax;
     QAction *aRevealToAll;
     QAction *aHide;
     QAction *aClone;

cockatrice/src/game_graphics/player/player_graphics_item.h

@@ -171,7 +171,7 @@ private:
     void setCounterMenuRegistered(AbstractCounter *widget, bool registered);
     /** @brief Returns the command zone's display height, or 0 if hidden. */
     [[nodiscard]] qreal totalCommandZoneHeight() const;
-    /** @brief Positions the command and stack zones vertically starting from base, updating base.y. */
+    /** @brief Positions the command and stack zones vertically starting from base. */
     void positionCommandAndStackZones(const QPointF &base);
 private slots:
     void updateBoundingRect();

cockatrice/src/game_graphics/zones/command_zone.h

@@ -36,11 +36,11 @@ constexpr qreal COMMAND_ZONE_WIDTH = CardDimensions::WIDTH_F * 1.5;
  * @class CommandZone
  * @brief Graphics layer for the command zone in Commander format games.
  *
- * Always visible when enabled. Supports multiple cards using a zigzag
- * horizontal stacking pattern: single cards display centered, multiple
- * cards alternate left-right with vertical overlap compression.
- * Can be minimized to 25% height via double-click.
+ * Always visible when enabled. Uses the generic vertical stacking layout
+ * with bottom overflow enabled. Can be minimized via double-click (25% height,
+ * or the tax-counter floor if higher).
  *
+ * @see SelectZone::layoutCardsVertically for the stacking algorithm
  * @see CommandZoneLogic for card data management
  * @see CommanderTaxCounter for the tax counter overlay
  */
@@ -50,7 +50,7 @@ class CommandZone : public SelectZone
 private:
     static constexpr double MINIMIZED_HEIGHT_RATIO = 0.25;
     int zoneHeight;                       ///< Full height in pixels when expanded
-    bool minimized = false;               ///< Whether zone is at 25% height
+    bool minimized = false;               ///< Whether zone is collapsed (25% height, or the tax-counter floor)
     int minimumHeight = 0;                ///< Floor for minimized height (e.g. to fit tax counters)
     QList<AbstractCounter *> taxCounters; ///< Registered tax counter widgets
 
@@ -77,11 +77,12 @@ public:
     [[nodiscard]] QRectF boundingRect() const override;
     /** @brief Paints the zone background using the Commander theme brush. */
     void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget) override;
-    /** @brief Repositions cards using zigzag horizontal stacking with overlap compression. */
+    /** @brief Repositions cards using vertical stacking with bottom overflow. */
     void reorganizeCards() override;
 
-    /** @brief Toggles between full and 25% minimized height. */
+    /** @brief Toggles between full and minimized height. */
     void toggleMinimized();
+    /** @brief Returns whether the zone is currently minimized. */
     [[nodiscard]] bool isMinimized() const;
     /** @brief Returns the current display height (full or minimized). */
     [[nodiscard]] qreal currentHeight() const;
@@ -100,9 +101,10 @@ public:
     void rearrangeTaxCounters();
 
 signals:
+    /** @brief Emitted when the zone's minimized state changes. */
     void minimizedChanged(bool isMinimized);
-    // Displayed height changed without a minimized-state change (e.g. tax counter toggled
-    // while minimized); lets neighbouring zones reposition.
+    /** @brief Emitted when display height changes without a minimized-state change (e.g. tax counter toggled while
+     * minimized). */
     void effectiveHeightChanged();
 
 protected: