[Doxygen] card_relation.h (#6298)

* Doxygen card_relation.h

Took 31 minutes

* Doxygen card_relation_type.h

Took 3 minutes

---------

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

libcockatrice_card/libcockatrice/card/relation/card_relation.h

@@ -6,19 +6,43 @@
 #include <QObject>
 #include <QString>
 
+/**
+ * @class CardRelation
+ * @ingroup Cards
+ *
+ * @brief Represents a relationship between two cards.
+ *
+ * CardRelation objects define directional relationships, such as:
+ * - One card attaching to another.
+ * - One card transforming into another.
+ * - One card creating another instance.
+ *
+ * Relations may also define metadata such as whether multiple creations
+ * are possible, whether the relation is persistent, and default counts.
+ */
 class CardRelation : public QObject
 {
     Q_OBJECT
 
 private:
-    QString name;
+    QString name;                ///< Name of the related card.
-    CardRelationType attachType;
+    CardRelationType attachType; ///< Type of attachment.
-    bool isCreateAllExclusion;
+    bool isCreateAllExclusion; ///< True if this relation should exclude multiple creations in "create all" operations.
-    bool isVariableCount;
+    bool isVariableCount;      ///< True if the number of creations is variable.
-    int defaultCount;
+    int defaultCount;          ///< Default number of cards created or involved.
-    bool isPersistent;
+    bool isPersistent;         ///< True if this relation persists (i.e. is not destroyed) on zone change.
 
 public:
+    /**
+     * @brief Constructs a CardRelation with optional parameters.
+     *
+     * @param _name Name of the related card.
+     * @param _attachType Type of attachment.
+     * @param _isCreateAllExclusion Whether this relation excludes mass creation.
+     * @param _isVariableCount Whether the count is variable.
+     * @param _defaultCount Default number for creations or transformations.
+     * @param _isPersistent Whether the relation persists across zone changes.
+     */
     explicit CardRelation(const QString &_name = QString(),
                           CardRelationType _attachType = CardRelationType::DoesNotAttach,
                           bool _isCreateAllExclusion = false,
@@ -26,45 +50,104 @@ public:
                           int _defaultCount = 1,
                           bool _isPersistent = false);
 
-    const QString &getName() const
+    /**
+     * @brief Returns the name of the related card.
+     *
+     * @return Name as QString reference.
+     */
+    [[nodiscard]] inline const QString &getName() const
     {
         return name;
     }
-    CardRelationType getAttachType() const
+
+    /**
+     * @brief Returns the type of attachment.
+     *
+     * @return Enum value representing the attachment type.
+     */
+    [[nodiscard]] CardRelationType getAttachType() const
     {
         return attachType;
     }
-    bool getDoesAttach() const
+
+    /**
+     * @brief Returns true if the card is attached to another.
+     *
+     * @return True if attached, false otherwise.
+     */
+    [[nodiscard]] bool getDoesAttach() const
     {
         return attachType != CardRelationType::DoesNotAttach;
     }
-    bool getDoesTransform() const
+
+    /**
+     * @brief Returns true if this card transforms into another card.
+     *
+     * @return True if it transforms, false otherwise.
+     */
+    [[nodiscard]] bool getDoesTransform() const
     {
         return attachType == CardRelationType::TransformInto;
     }
 
-    QString getAttachTypeAsString() const
+    /**
+     * @brief Returns a string description of the attachment type.
+     *
+     * @return "attach" for AttachTo, "transform" for TransformInto, empty string otherwise.
+     */
+    [[nodiscard]] QString getAttachTypeAsString() const
     {
         return cardAttachTypeToString(attachType);
     }
 
-    bool getCanCreateAnother() const
+    /**
+     * @brief Determines whether another instance can be created.
+     *
+     * @return True if creation is allowed, false if constrained by attachment.
+     */
+    [[nodiscard]] bool getCanCreateAnother() const
     {
         return !getDoesAttach();
     }
-    bool getIsCreateAllExclusion() const
+
+    /**
+     * @brief Returns whether this relation is excluded from "create all" operations.
+     *
+     * @return True if excluded, false otherwise.
+     */
+    [[nodiscard]] bool getIsCreateAllExclusion() const
     {
         return isCreateAllExclusion;
     }
-    bool getIsVariable() const
+
+    /**
+     * @brief Returns whether the relation count is variable.
+     *
+     * @return True if variable, false otherwise.
+     */
+    [[nodiscard]] bool getIsVariable() const
     {
         return isVariableCount;
     }
-    int getDefaultCount() const
+
+    /**
+     * @brief Returns the default count of related cards.
+     *
+     * @return Integer representing default number.
+     */
+    [[nodiscard]] int getDefaultCount() const
     {
         return defaultCount;
     }
-    bool getIsPersistent() const
+
+    /**
+     * @brief Returns whether the relation is persistent.
+     *
+     * Persistent relations are not destroyed on zone changes.
+     *
+     * @return True if persistent, false otherwise.
+     */
+    [[nodiscard]] bool getIsPersistent() const
     {
         return isPersistent;
     }

libcockatrice_card/libcockatrice/card/relation/card_relation_type.h

@@ -4,7 +4,13 @@
 #include <QString>
 
 /**
- * Represents how a card relates to another (attach, transform, etc.).
+ * @enum CardRelationType
+ * @ingroup Cards
+ * @brief Types of attachments between cards.
+ *
+ * DoesNotAttach: No attachment is present.
+ * AttachTo: This card attaches to another card.
+ * TransformInto: This card transforms into another card.
  */
 enum class CardRelationType
 {
@@ -13,7 +19,7 @@ enum class CardRelationType
     TransformInto = 2,
 };
 
-// Optional helper
+// Helper function to transform the enum values into human-readable strings
 inline QString cardAttachTypeToString(CardRelationType type)
 {
     switch (type) {