[Doxygen] Card Database and related (#6303)

Took 29 minutes


Took 24 seconds

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

libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h

@@ -1,9 +1,3 @@
-/**
- * @file card_database_parser.h
- * @ingroup CardDatabaseParsers
- * @brief The ICardDatabaseParser defines the base interface for parser sub-classes.
- */
-
 #ifndef CARDDATABASE_PARSER_H
 #define CARDDATABASE_PARSER_H
 
@@ -14,35 +8,76 @@
 
 #define COCKATRICE_XML_XSI_NAMESPACE "http://www.w3.org/2001/XMLSchema-instance"
 
+/**
+ * @class ICardDatabaseParser
+ * @ingroup CardDatabase
+ * @brief Defines the base parser interface (ICardDatabaseParser) for all card database parsers.
+ *
+ * Provides methods for checking file compatibility, parsing, and saving card databases.
+ * Also provides shared access to the global set list for cross-referencing.
+ */
 class ICardDatabaseParser : public QObject
 {
     Q_OBJECT
 public:
     ~ICardDatabaseParser() override = default;
 
+    /**
+     * @brief Checks whether this parser can parse the given file.
+     * @param name File name (used for extension checks).
+     * @param device QIODevice representing the file content.
+     * @return true if the parser can handle this file.
+     */
     virtual bool getCanParseFile(const QString &name, QIODevice &device) = 0;
+
+    /**
+     * @brief Parses a database file and emits addCard/addSet signals.
+     * @param device QIODevice representing the file content.
+     */
     virtual void parseFile(QIODevice &device) = 0;
+
+    /**
+     * @brief Saves card and set data to a file.
+     * @param sets Map of sets to save.
+     * @param cards Map of cards to save.
+     * @param fileName Target file path.
+     * @param sourceUrl Optional source URL of the database.
+     * @param sourceVersion Optional version string of the source.
+     * @return true if save succeeded.
+     */
     virtual bool saveToFile(SetNameMap sets,
                             CardNameMap cards,
                             const QString &fileName,
                             const QString &sourceUrl = "unknown",
                             const QString &sourceVersion = "unknown") = 0;
+
+    /** @brief Clears the cached global set list. */
     static void clearSetlist();
 
 protected:
-    /*
-     * A cached list of the available sets, needed to cross-reference sets from cards.
-     * Shared between all parsers
-     */
+    /** @brief Cached global list of sets shared between all parsers. */
     static SetNameMap sets;
 
+    /**
+     * @brief Internal helper to add a set to the global set cache.
+     * @param setName Short set name.
+     * @param longName Optional full name.
+     * @param setType Optional set type string.
+     * @param releaseDate Optional release date.
+     * @param priority Optional priority (fallback if not specified).
+     * @return Pointer to the added or existing CardSet instance.
+     */
     CardSetPtr internalAddSet(const QString &setName,
                               const QString &longName = "",
                               const QString &setType = "",
                               const QDate &releaseDate = QDate(),
                               const CardSet::Priority priority = CardSet::PriorityFallback);
+
 signals:
+    /** Emitted when a card is loaded from the database. */
     void addCard(CardInfoPtr card);
+
+    /** Emitted when a set is loaded from the database. */
     void addSet(CardSetPtr set);
 };
 

libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h

@@ -1,9 +1,3 @@
-/**
- * @file cockatrice_xml_3.h
- * @ingroup CardDatabaseParsers
- * @brief The CockatriceXml3Parser is capable of parsing version 3 of the Cockatrice XML Schema.
- */
-
 #ifndef COCKATRICE_XML3_H
 #define COCKATRICE_XML3_H
 
@@ -14,14 +8,44 @@
 
 inline Q_LOGGING_CATEGORY(CockatriceXml3Log, "cockatrice_xml.xml_3_parser");
 
+/**
+ * @class CockatriceXml3Parser
+ * @ingroup CardDatabase
+ * @brief Parses version 3 of the Cockatrice XML Schema.
+ *
+ * This parser reads a Cockatrice XML3 database and emits CardInfoPtr
+ * and CardSetPtr objects. All card properties are read individually.
+ *
+ * @note Differences from v4:
+ * - No <prop> block; properties are hardcoded (manacost, cmc, type, pt, loyalty, etc.).
+ * - No set priority field.
+ * - No support for rebalanced cards or preferences.
+ * - Related cards support only attach, exclude, variable, and count attributes.
+ */
 class CockatriceXml3Parser : public ICardDatabaseParser
 {
     Q_OBJECT
 public:
     CockatriceXml3Parser() = default;
     ~CockatriceXml3Parser() override = default;
+
+    /**
+     * @brief Determines if the parser can handle this file.
+     * @param name File name.
+     * @param device Open QIODevice containing the XML.
+     * @return True if the file is a Cockatrice XML3 database.
+     */
     bool getCanParseFile(const QString &name, QIODevice &device) override;
+
+    /**
+     * @brief Parse the XML database.
+     * @param device Open QIODevice positioned at start of file.
+     */
     void parseFile(QIODevice &device) override;
+
+    /**
+     * @brief Save sets and cards back to an XML3 file.
+     */
     bool saveToFile(SetNameMap _sets,
                     CardNameMap cards,
                     const QString &fileName,
@@ -29,8 +53,25 @@ public:
                     const QString &sourceVersion = "unknown") override;
 
 private:
+    /**
+     * @brief Load all <card> elements from the XML stream.
+     * @param xml The open QXmlStreamReader positioned at the <cards> element.
+     * Parses each <card> node and emits addCard signals for each CardInfoPtr created.
+     */
     void loadCardsFromXml(QXmlStreamReader &xml);
+
+    /**
+     * @brief Load all <set> elements from the XML stream.
+     * @param xml The open QXmlStreamReader positioned at the <sets> element.
+     * Parses each <set> node and adds them to the shared set cache.
+     */
     void loadSetsFromXml(QXmlStreamReader &xml);
+
+    /**
+     * @brief Extracts the main card type from a full type string.
+     * @param type The full type string (e.g., "Legendary Artifact Creature - Golem")
+     * @return The primary type (e.g., "Creature").
+     */
     QString getMainCardType(QString &type);
 };
 

libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h

@@ -1,9 +1,3 @@
-/**
- * @file cockatrice_xml_4.h
- * @ingroup CardDatabaseParsers
- * @brief The CockatriceXml4Parser is capable of parsing version 4 of the Cockatrice XML Schema.
- */
-
 #ifndef COCKATRICE_XML4_H
 #define COCKATRICE_XML4_H
 
@@ -15,14 +9,46 @@
 
 inline Q_LOGGING_CATEGORY(CockatriceXml4Log, "cockatrice_xml.xml_4_parser");
 
+/**
+ * @class CockatriceXml4Parser
+ * @ingroup CardDatabase
+ * @brief Parses version 4 of the Cockatrice XML Schema.
+ *
+ * This parser reads a Cockatrice XML4 database and emits CardInfoPtr
+ * and CardSetPtr objects. Card properties are read inside <prop> blocks,
+ * making the parser more extensible and schema-compliant.
+ *
+ * @note Differences from v3:
+ * - Card properties are stored in <prop> blocks as a QVariantHash.
+ * - Sets can include a <priority> element.
+ * - Supports user preferences via ICardPreferenceProvider (e.g., skipping rebalanced cards).
+ * - Related cards support persistent relations and multiple attach types (e.g., transform).
+ * - More robust serialization; easier to extend schema in the future.
+ */
 class CockatriceXml4Parser : public ICardDatabaseParser
 {
     Q_OBJECT
 public:
-    CockatriceXml4Parser(ICardPreferenceProvider *cardPreferenceProvider);
+    explicit CockatriceXml4Parser(ICardPreferenceProvider *cardPreferenceProvider);
     ~CockatriceXml4Parser() override = default;
+
+    /**
+     * @brief Determines if the parser can handle this file.
+     * @param name File name.
+     * @param device Open QIODevice containing the XML.
+     * @return True if the file is a Cockatrice XML4 database.
+     */
     bool getCanParseFile(const QString &name, QIODevice &device) override;
+
+    /**
+     * @brief Parse the XML database.
+     * @param device Open QIODevice positioned at start of file.
+     */
     void parseFile(QIODevice &device) override;
+
+    /**
+     * @brief Save sets and cards back to an XML4 file.
+     */
     bool saveToFile(SetNameMap _sets,
                     CardNameMap cards,
                     const QString &fileName,
@@ -30,10 +56,27 @@ public:
                     const QString &sourceVersion = "unknown") override;
 
 private:
-    ICardPreferenceProvider *cardPreferenceProvider;
+    ICardPreferenceProvider *cardPreferenceProvider; ///< Interface to handle user preferences
 
+    /**
+     * @brief Loads a generic <prop> block from a <card> element.
+     * @param xml The open QXmlStreamReader positioned at a <prop> element.
+     * @return A QVariantHash mapping property names to values.
+     */
     QVariantHash loadCardPropertiesFromXml(QXmlStreamReader &xml);
+
+    /**
+     * @brief Load all <card> elements from the XML stream.
+     * @param xml The open QXmlStreamReader positioned at the <cards> element.
+     * Honors the user's preference regarding rebalanced cards.
+     */
     void loadCardsFromXml(QXmlStreamReader &xml);
+
+    /**
+     * @brief Load all <set> elements from the XML stream.
+     * @param xml The open QXmlStreamReader positioned at the <sets> element.
+     * Parses <set> nodes including priority information.
+     */
     void loadSetsFromXml(QXmlStreamReader &xml);
 };