Modularize and Doxygen decklist.cpp (#6099)

cockatrice/src/client/tabs/tab_deck_storage.cpp

@@ -5,7 +5,7 @@
 #include "../../server/remote/remote_decklist_tree_widget.h"
 #include "../../settings/cache_settings.h"
 #include "../get_text_with_max.h"
-#include "decklist.h"
+#include "deck_list.h"
 #include "pb/command_deck_del.pb.h"
 #include "pb/command_deck_del_dir.pb.h"
 #include "pb/command_deck_download.pb.h"

cockatrice/src/client/tapped_out_interface.cpp

@@ -1,6 +1,7 @@
 #include "tapped_out_interface.h"
 
-#include "decklist.h"
+#include "deck_list.h"
+#include "deck_list_card_node.h"
 
 #include <QDesktopServices>
 #include <QMessageBox>

cockatrice/src/client/tapped_out_interface.h

@@ -2,7 +2,7 @@
 #define TAPPEDOUT_INTERFACE_H
 
 #include "../game/cards/card_database.h"
-#include "decklist.h"
+#include "deck_list.h"
 
 #include <QLoggingCategory>
 #include <QObject>

cockatrice/src/client/ui/widgets/deck_analytics/deck_analytics_widget.h

@@ -11,7 +11,7 @@
 #include <QScrollArea>
 #include <QVBoxLayout>
 #include <QWidget>
-#include <decklist.h>
+#include <deck_list.h>
 
 class DeckAnalyticsWidget : public QWidget
 {

cockatrice/src/client/ui/widgets/deck_analytics/mana_base_widget.cpp

@@ -8,7 +8,7 @@
 
 #include <QHash>
 #include <QRegularExpression>
-#include <decklist.h>
+#include <deck_list.h>
 
 ManaBaseWidget::ManaBaseWidget(QWidget *parent, DeckListModel *_deckListModel)
     : QWidget(parent), deckListModel(_deckListModel)

cockatrice/src/client/ui/widgets/deck_analytics/mana_base_widget.h

@@ -6,7 +6,7 @@
 
 #include <QHBoxLayout>
 #include <QWidget>
-#include <decklist.h>
+#include <deck_list.h>
 #include <utility>
 
 class ManaBaseWidget : public QWidget

cockatrice/src/client/ui/widgets/deck_analytics/mana_curve_widget.cpp

@@ -7,7 +7,7 @@
 #include "../general/display/banner_widget.h"
 #include "../general/display/bar_widget.h"
 
-#include <decklist.h>
+#include <deck_list.h>
 #include <unordered_map>
 
 ManaCurveWidget::ManaCurveWidget(QWidget *parent, DeckListModel *_deckListModel)

cockatrice/src/client/ui/widgets/deck_analytics/mana_devotion_widget.cpp

@@ -7,7 +7,7 @@
 #include "../general/display/banner_widget.h"
 #include "../general/display/bar_widget.h"
 
-#include <decklist.h>
+#include <deck_list.h>
 #include <iostream>
 #include <regex>
 #include <string>

cockatrice/src/client/ui/widgets/deck_analytics/mana_devotion_widget.h

@@ -6,7 +6,7 @@
 
 #include <QHBoxLayout>
 #include <QWidget>
-#include <decklist.h>
+#include <deck_list.h>
 #include <utility>
 
 class ManaDevotionWidget : public QWidget

cockatrice/src/deck/deck_list_model.h

@@ -2,7 +2,9 @@
 #define DECKLISTMODEL_H
 
 #include "../game/cards/exact_card.h"
-#include "decklist.h"
+#include "abstract_deck_list_card_node.h"
+#include "deck_list.h"
+#include "deck_list_card_node.h"
 
 #include <QAbstractItemModel>
 #include <QList>
@@ -12,19 +14,35 @@ class CardDatabase;
 class QPrinter;
 class QTextCursor;
 
+/**
+ * @brief Specifies the criteria used to group cards in the DeckListModel.
+ */
 enum DeckListModelGroupCriteria
 {
-    MAIN_TYPE,
-    MANA_COST,
-    COLOR
+    MAIN_TYPE, /**< Group cards by their main type (e.g., creature, instant). */
+    MANA_COST, /**< Group cards by their mana cost. */
+    COLOR      /**< Group cards by their color identity. */
 };
 
+/**
+ * @brief Adapter node that wraps a DecklistCardNode for use in the DeckListModel tree.
+ *
+ * This class forwards all property accessors (name, number, provider ID, set info, etc.)
+ * to the underlying DecklistCardNode. It exists so the model can represent cards
+ * in the same hierarchy as InnerDecklistNode containers.
+ */
 class DecklistModelCardNode : public AbstractDecklistCardNode
 {
 private:
-    DecklistCardNode *dataNode;
+    DecklistCardNode *dataNode; /**< Pointer to the underlying data node. */
 
 public:
+    /**
+     * @brief Constructs a model node wrapping a DecklistCardNode.
+     * @param _dataNode The underlying DecklistCardNode to wrap.
+     * @param _parent The parent InnerDecklistNode in the model tree.
+     * @param position Optional position to insert in parent (-1 appends at end).
+     */
     DecklistModelCardNode(DecklistCardNode *_dataNode, InnerDecklistNode *_parent, int position = -1)
         : AbstractDecklistCardNode(_parent, position), dataNode(_dataNode)
     {
@@ -69,6 +87,11 @@ public:
     {
         dataNode->setCardCollectorNumber(_cardSetNumber);
     }
+
+    /**
+     * @brief Returns the underlying data node.
+     * @return Pointer to the DecklistCardNode wrapped by this node.
+     */
     DecklistCardNode *getDataNode() const
     {
         return dataNode;
@@ -79,24 +102,68 @@ public:
     }
 };
 
+/**
+ * @brief Qt model representing a decklist for use in views (tree/table).
+ *
+ * DeckListModel is a QAbstractItemModel that exposes the structure of a deck
+ * (zones and cards) to Qt views. It organizes cards hierarchically under
+ * InnerDecklistNode containers and supports grouping, sorting, adding/removing
+ * cards, and printing decklists.
+ *
+ * Signals:
+ * - deckHashChanged(): emitted when the deck contents change in a way that
+ *   affects its hash.
+ *
+ * Slots:
+ * - rebuildTree(): rebuilds the model structure from the underlying DeckLoader.
+ * - printDeckList(): renders the decklist to a QPrinter.
+ */
 class DeckListModel : public QAbstractItemModel
 {
     Q_OBJECT
 private slots:
+    /**
+     * @brief Rebuilds the model tree from the underlying DeckLoader.
+     *
+     * This updates all indices and ensures the model reflects the current
+     * state of the deck.
+     */
     void rebuildTree();
+
 public slots:
+    /**
+     * @brief Prints the decklist to the provided QPrinter.
+     * @param printer The printer to render the decklist to.
+     */
     void printDeckList(QPrinter *printer);
+
 signals:
+    /**
+     * @brief Emitted whenever the deck hash changes due to modifications in the model.
+     */
     void deckHashChanged();
 
 public:
     explicit DeckListModel(QObject *parent = nullptr);
     ~DeckListModel() override;
+
+    /**
+     * @brief Returns the root index of the model.
+     * @return QModelIndex representing the root node.
+     */
     QModelIndex getRoot() const
     {
         return nodeToIndex(root);
     };
+
+    /**
+     * @brief Returns the value of the grouping category for a card based on the current criteria.
+     * @param info Pointer to card information.
+     * @return String representing the value of the current grouping criteria for the card.
+     */
     QString getGroupCriteriaForCard(CardInfoPtr info) const;
+
+    // Qt model overrides
     int rowCount(const QModelIndex &parent) const override;
     int columnCount(const QModelIndex & /*parent*/ = QModelIndex()) const override;
     QVariant data(const QModelIndex &index, int role) const override;
@@ -106,31 +173,75 @@ public:
     Qt::ItemFlags flags(const QModelIndex &index) const override;
     bool setData(const QModelIndex &index, const QVariant &value, int role) override;
     bool removeRows(int row, int count, const QModelIndex &parent) override;
+
+    /**
+     * @brief Finds a card by name, zone, and optional identifiers.
+     * @param cardName The card's name.
+     * @param zoneName The zone to search in (main/side/etc.).
+     * @param providerId Optional provider-specific ID.
+     * @param cardNumber Optional collector number.
+     * @return QModelIndex of the card, or invalid index if not found.
+     */
     QModelIndex findCard(const QString &cardName,
                          const QString &zoneName,
                          const QString &providerId = "",
                          const QString &cardNumber = "") const;
+
+    /**
+     * @brief Adds a card using the preferred printing if available.
+     *
+     * @param cardName Name of the card to add.
+     * @param zoneName Zone to insert the card into.
+     * @param abAddAnyway Whether to add the card even if resolution fails.
+     * @return QModelIndex pointing to the newly inserted card node.
+     */
     QModelIndex addPreferredPrintingCard(const QString &cardName, const QString &zoneName, bool abAddAnyway);
+
+    /**
+     * @brief Adds an ExactCard to the specified zone.
+     * @param card The card to add.
+     * @param zoneName The zone to insert the card into.
+     * @return QModelIndex pointing to the newly inserted card node.
+     */
     QModelIndex addCard(const ExactCard &card, const QString &zoneName);
+
+    /**
+     * @brief Determines the sorted insertion row for a card.
+     * @param parent The parent node where the card will be inserted.
+     * @param cardInfo The card info to insert.
+     * @return Row index where the card should be inserted to maintain sort order.
+     */
     int findSortedInsertRow(InnerDecklistNode *parent, CardInfoPtr cardInfo) const;
+
     void sort(int column, Qt::SortOrder order) override;
+
+    /**
+     * @brief Removes all cards and resets the model.
+     */
     void cleanList();
     DeckLoader *getDeckList() const
     {
         return deckList;
     }
     void setDeckList(DeckLoader *_deck);
+
     QList<ExactCard> getCards() const;
     QList<ExactCard> getCardsForZone(const QString &zoneName) const;
     QList<QString> *getZones() const;
+
+    /**
+     * @brief Sets the criteria used to group cards in the model.
+     * @param newCriteria The new grouping criteria.
+     */
     void setActiveGroupCriteria(DeckListModelGroupCriteria newCriteria);
 
 private:
-    DeckLoader *deckList;
-    InnerDecklistNode *root;
+    DeckLoader *deckList;    /**< Pointer to the deck loader providing the underlying data. */
+    InnerDecklistNode *root; /**< Root node of the model tree. */
     DeckListModelGroupCriteria activeGroupCriteria = DeckListModelGroupCriteria::MAIN_TYPE;
-    int lastKnownColumn;
-    Qt::SortOrder lastKnownOrder;
+    int lastKnownColumn;          /**< Last column used for sorting. */
+    Qt::SortOrder lastKnownOrder; /**< Last known sort order. */
+
     InnerDecklistNode *createNodeIfNeeded(const QString &name, InnerDecklistNode *parent);
     QModelIndex nodeToIndex(AbstractDecklistNode *node) const;
     DecklistModelCardNode *findCardNode(const QString &cardName,

cockatrice/src/deck/deck_loader.cpp

@@ -3,7 +3,8 @@
 #include "../game/cards/card_database.h"
 #include "../game/cards/card_database_manager.h"
 #include "../main.h"
-#include "decklist.h"
+#include "deck_list.h"
+#include "deck_list_card_node.h"
 
 #include <QApplication>
 #include <QClipboard>

cockatrice/src/deck/deck_loader.h

@@ -1,7 +1,7 @@
 #ifndef DECK_LOADER_H
 #define DECK_LOADER_H
 
-#include "decklist.h"
+#include "deck_list.h"
 
 #include <QLoggingCategory>
 

cockatrice/src/deck/deck_stats_interface.cpp

@@ -1,6 +1,7 @@
 #include "deck_stats_interface.h"
 
-#include "decklist.h"
+#include "deck_list.h"
+#include "deck_list_card_node.h"
 
 #include <QDesktopServices>
 #include <QMessageBox>

cockatrice/src/deck/deck_stats_interface.h

@@ -2,7 +2,7 @@
 #define DECKSTATS_INTERFACE_H
 
 #include "../game/cards/card_database.h"
-#include "decklist.h"
+#include "deck_list.h"
 
 #include <QObject>
 

cockatrice/src/dialogs/dlg_create_token.cpp

@@ -5,7 +5,7 @@
 #include "../game/cards/card_database_model.h"
 #include "../main.h"
 #include "../settings/cache_settings.h"
-#include "decklist.h"
+#include "deck_list.h"
 #include "trice_limits.h"
 
 #include <QCheckBox>

cockatrice/src/game/deckview/deck_view.cpp

@@ -3,7 +3,8 @@
 #include "../../client/ui/theme_manager.h"
 #include "../../game/cards/card_info.h"
 #include "../../settings/cache_settings.h"
-#include "decklist.h"
+#include "deck_list.h"
+#include "deck_list_card_node.h"
 
 #include <QApplication>
 #include <QGraphicsSceneMouseEvent>