Doxygen card_set.h and card_set_list.h (#6299)

Took 13 minutes

Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>

libcockatrice_card/libcockatrice/card/set/card_set.h

@@ -13,31 +13,65 @@ using CardInfoPtr = QSharedPointer<CardInfo>;
 class CardSet;
 using CardSetPtr = QSharedPointer<CardSet>;
 
+/**
+ * @class CardSet
+ * @ingroup Cards
+ *
+ * @brief A collection of cards grouped under a common identifier.
+ *
+ * A set serves both as metadata (identifier, title, category, release date, and priority)
+ * and as a container of all cards that belong to it. Each set can be enabled/disabled
+ * and marked as known/unknown depending on context.
+ *
+ * The class inherits from `QList<CardInfoPtr>`, so it can be iterated over directly
+ * to access its contents.
+ *
+ * Typical usage:
+ * - Query metadata such as identifier, category, or release date.
+ * - Enable or disable sets according to user preference.
+ * - Store and retrieve CardInfo objects associated with the set.
+ */
 class CardSet : public QList<CardInfoPtr>
 {
 public:
+    /**
+     * @enum Priority
+     * @brief Defines relative ordering and importance of sets.
+     */
     enum Priority
     {
-        PriorityFallback = 0,
-        PriorityPrimary = 10,
-        PrioritySecondary = 20,
-        PriorityReprint = 30,
-        PriorityOther = 40,
-        PriorityLowest = 100,
+        PriorityFallback = 0,   ///< Used when no other priority is defined.
+        PriorityPrimary = 10,   ///< Primary, canonical set.
+        PrioritySecondary = 20, ///< Secondary but relevant.
+        PriorityReprint = 30,   ///< Duplicate or reprint category.
+        PriorityOther = 40,     ///< Miscellaneous grouping.
+        PriorityLowest = 100,   ///< Lowest sorting priority.
     };
 
-    static const char *TOKENS_SETNAME;
+    static const char *TOKENS_SETNAME; ///< Reserved identifier for token-like sets.
 
 private:
-    QSharedPointer<ICardSetPriorityController> priorityController;
-    QString shortName, longName;
-    unsigned int sortKey;
-    QDate releaseDate;
-    QString setType;
-    Priority priority;
-    bool enabled, isknown;
+    QSharedPointer<ICardSetPriorityController> priorityController; ///< Interface to the card set priority controller.
+    QString shortName;                                             ///< Short identifier for the set.
+    QString longName;                                              ///< Full name for the set.
+    unsigned int sortKey;                                          ///< Custom numeric sort key.
+    QDate releaseDate;                                             ///< Release date, may be empty if unknown.
+    QString setType;                                               ///< Type/category label for the set.
+    Priority priority;                                             ///< Priority level for sorting and relevance.
+    bool enabled;                                                  ///< Whether the set is active/enabled.
+    bool isknown;                                                  ///< Whether the set is considered known.
 
 public:
+    /**
+     * @brief Constructs a CardSet.
+     *
+     * @param priorityController Interface to a card set priority controller.
+     * @param _shortName Identifier string.
+     * @param _longName Full descriptive name.
+     * @param _setType Type/category string.
+     * @param _releaseDate Release date (optional).
+     * @param _priority Sorting/priority level.
+     */
     explicit CardSet(ICardSetPriorityController *priorityController,
                      const QString &_shortName = QString(),
                      const QString &_longName = QString(),
@@ -45,6 +79,17 @@ public:
                      const QDate &_releaseDate = QDate(),
                      const Priority _priority = PriorityFallback);
 
+    /**
+     * @brief Creates and returns a new shared CardSet instance.
+     *
+     * @param priorityController Interface to a card set priority controller.
+     * @param _shortName Identifier string.
+     * @param _longName Full descriptive name.
+     * @param _setType Type/category string.
+     * @param _releaseDate Release date (optional).
+     * @param _priority Sorting/priority level.
+     * @return A shared pointer to the new CardSet.
+     */
     static CardSetPtr newInstance(ICardSetPriorityController *priorityController,
                                   const QString &_shortName = QString(),
                                   const QString &_longName = QString(),
@@ -52,65 +97,131 @@ public:
                                   const QDate &_releaseDate = QDate(),
                                   const Priority _priority = PriorityFallback);
 
+    /**
+     * @brief Returns a safe, sanitized version of the short name.
+     *
+     * Intended for file paths or identifiers where only certain
+     * characters are allowed.
+     *
+     * @return Sanitized short name.
+     */
     QString getCorrectedShortName() const;
 
+    /// @return Short identifier of the set.
     QString getShortName() const
     {
         return shortName;
     }
+
+    /// @return Descriptive name of the set.
     QString getLongName() const
     {
         return longName;
     }
+
+    /// @return Type/category string of the set.
     QString getSetType() const
     {
         return setType;
     }
+
+    /// @return Release date of the set.
     QDate getReleaseDate() const
     {
         return releaseDate;
     }
+
+    /// @return Priority level of the set.
     Priority getPriority() const
     {
         return priority;
     }
 
+    /**
+     * @brief Sets the full name of the set.
+     * @param _longName New full name.
+     */
     void setLongName(const QString &_longName)
     {
         longName = _longName;
     }
+
+    /**
+     * @brief Sets the category/type of the set.
+     * @param _setType New category string.
+     */
     void setSetType(const QString &_setType)
     {
         setType = _setType;
     }
+
+    /**
+     * @brief Sets the release date of the set.
+     * @param _releaseDate New release date.
+     */
     void setReleaseDate(const QDate &_releaseDate)
     {
         releaseDate = _releaseDate;
     }
+
+    /**
+     * @brief Updates the priority of the set.
+     * @param _priority New priority value.
+     */
+
     void setPriority(const Priority _priority)
     {
         priority = _priority;
     }
 
+    /**
+     * @brief Loads state values (enabled, known, sort key) from configuration.
+     *
+     * Reads external configuration and applies it to this set.
+     */
     void loadSetOptions();
+
+    /// @return The sort key assigned to this set.
     int getSortKey() const
     {
         return sortKey;
     }
+
+    /**
+     * @brief Assigns a new sort key to this set.
+     * @param _sortKey The numeric key to use for sorting.
+     */
     void setSortKey(unsigned int _sortKey);
 
+    /// @return True if the set is enabled.
     bool getEnabled() const
     {
         return enabled;
     }
+
+    /**
+     * @brief Enables or disables the set.
+     * @param _enabled True to enable, false to disable.
+     */
     void setEnabled(bool _enabled);
 
+    /// @return True if the set is considered known.
     bool getIsKnown() const
     {
         return isknown;
     }
+
+    /**
+     * @brief Marks the set as known or unknown.
+     * @param _isknown True if known, false if unknown.
+     */
     void setIsKnown(bool _isknown);
 
+    /**
+     * @brief Determines whether the set has incomplete metadata and should be ignored.
+     *
+     * @return True if the long name, type, and release date are all empty.
+     */
     bool getIsKnownIgnored() const
     {
         return longName.length() + setType.length() + releaseDate.toString().length() == 0;

libcockatrice_card/libcockatrice/card/set/card_set_list.h

@@ -6,20 +6,97 @@
 #include <QList>
 #include <QStringList>
 
+/**
+ * @class CardSetList
+ * @ingroup Cards
+ *
+ * @brief A list-like container for CardSet objects with extended management methods.
+ *
+ * Extends `QList<CardSetPtr>` by adding convenience operations for sorting,
+ * enabling/disabling sets, and tracking known/unknown status. Unlike a plain
+ * list, this container provides domain-specific functionality for handling
+ * groups of sets in bulk.
+ */
 class CardSetList : public QList<CardSetPtr>
 {
 private:
+    /**
+     * @class KeyCompareFunctor
+     * @brief Internal comparison functor for sorting by sort key.
+     *
+     * Used internally by `sortByKey()` to order sets consistently
+     * according to their assigned numeric sort keys.
+     */
     class KeyCompareFunctor;
 
 public:
+    /**
+     * @brief Sorts the set list by each set’s assigned sort key.
+     *
+     * Uses KeyCompareFunctor internally. If two sets share the
+     * same sort key, their relative order is unspecified.
+     */
     void sortByKey();
+
+    /**
+     * @brief Reassigns sort keys based on the current order.
+     *
+     * Calls defaultSort() and then assigns sequential sort keys
+     * to all sets according to their resulting positions, replacing
+     * any existing sort keys to ensure consistent ordering.
+     */
     void guessSortKeys();
+
+    /**
+     * @brief Enables all sets that are unknown or ignored.
+     *
+     * Sets that are not marked as known and not ignored are marked as known
+     * and enabled. Ignored-known sets are also enabled, but remain ignored.
+     */
     void enableAllUnknown();
+
+    /**
+     * @brief Enables all sets in the list.
+     *
+     * Equivalent to calling `setEnabled(true)` on each entry.
+     */
     void enableAll();
+
+    /**
+     * @brief Marks all sets as known and adjusts their enabled state.
+     *
+     * Unknown, non-ignored sets become known and disabled.
+     * Ignored-known sets are enabled if they were previously disabled.
+     */
     void markAllAsKnown();
+
+    /**
+     * @brief Counts the number of sets that are currently enabled.
+     *
+     * @return Integer count of enabled sets.
+     */
     int getEnabledSetsNum();
+
+    /**
+     * @brief Counts the number of sets that are currently unknown.
+     *
+     * @return Integer count of unknown sets.
+     */
     int getUnknownSetsNum();
+
+    /**
+     * @brief Collects the short names of all sets marked as unknown.
+     *
+     * @return A list of unknown set names.
+     */
     QStringList getUnknownSetsNames();
+
+    /**
+     * @brief Sorts the list by default rules.
+     *
+     * Orders sets first by priority (ascending), then by release date
+     * (most recent first), and finally alphabetically by short name.
+     */
     void defaultSort();
 };