[Doxygen] Card Picture Loader (#6315)

* [Doxygen] Card Picture Loader

Took 25 minutes

Took 16 minutes

# Commit time for manual adjustment:
# Took 12 seconds


Took 14 seconds

* Remove placeholder file description.

Took 1 minute

* ... but do group PictureLoader again

Took 28 seconds

* Link to methods directly.

Took 6 minutes

* Forward declaration.

Took 49 seconds

* Remove redundant .cpp function documentation.

Took 15 minutes

* More fixes.

Took 7 minutes

---------

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

cockatrice/src/interface/card_picture_loader/card_picture_loader.h

@@ -1,9 +1,3 @@
-/**
- * @file card_picture_loader.h
- * @ingroup PictureLoader
- * @brief TODO: Document this.
- */
-
 #ifndef CARD_PICTURE_LOADER_H
 #define CARD_PICTURE_LOADER_H
 
@@ -16,10 +10,37 @@
 inline Q_LOGGING_CATEGORY(CardPictureLoaderLog, "card_picture_loader");
 inline Q_LOGGING_CATEGORY(CardPictureLoaderCardBackCacheFailLog, "card_picture_loader.card_back_cache_fail");
 
+/**
+ * @class CardPictureLoader
+ * @ingroup PictureLoader
+ * @brief Singleton class to manage card image loading and caching. Provides functionality to asynchronously load,
+ * cache, and manage card images for the client.
+ *
+ * This class is a singleton and handles:
+ * - Loading card images from disk or network.
+ * - Caching images in QPixmapCache for fast reuse.
+ * - Providing themed card backs, including fallback and in-progress/failed states.
+ * - Emitting updates when pixmaps are loaded.
+ *
+ * It interacts with CardPictureLoaderWorker for background loading and
+ * CardPictureLoaderStatusBar to display loading progress in the main window.
+ *
+ * Provides static accessors for:
+ * - Card images by ExactCard.
+ * - Card back images (normal, in-progress, failed).
+ * - Cache management (clearPixmapCache(), clearNetworkCache(), cacheCardPixmaps(const QList<ExactCard> &cards)).
+ *
+ * Uses a worker thread for asynchronous image loading and a status bar widget
+ * to track load progress.
+ */
 class CardPictureLoader : public QObject
 {
     Q_OBJECT
 public:
+    /**
+     * @brief Access the singleton instance of CardPictureLoader.
+     * @return Reference to the singleton.
+     */
     static CardPictureLoader &getInstance()
     {
         static CardPictureLoader instance;
@@ -29,30 +50,87 @@ public:
 private:
     explicit CardPictureLoader();
     ~CardPictureLoader() override;
-    // Singleton - Don't implement copy constructor and assign operator
-    CardPictureLoader(CardPictureLoader const &);
-    void operator=(CardPictureLoader const &);
 
-    CardPictureLoaderWorker *worker;
-    CardPictureLoaderStatusBar *statusBar;
+    // Disable copy and assignment for singleton
+    CardPictureLoader(CardPictureLoader const &) = delete;
+    void operator=(CardPictureLoader const &) = delete;
+
+    CardPictureLoaderWorker *worker;       ///< Worker thread for async image loading
+    CardPictureLoaderStatusBar *statusBar; ///< Status bar widget showing load progress
 
 public:
+    /**
+     * @brief Retrieve a card pixmap, either from cache or enqueued for loading.
+     * @param pixmap Reference to QPixmap where result will be stored.
+     * @param card ExactCard to load.
+     * @param size Desired size of pixmap.
+     */
     static void getPixmap(QPixmap &pixmap, const ExactCard &card, QSize size);
+
+    /**
+     * @brief Retrieve a generic card back pixmap.
+     * @param pixmap Reference to QPixmap where result will be stored.
+     * @param size Desired size of pixmap.
+     */
     static void getCardBackPixmap(QPixmap &pixmap, QSize size);
+
+    /**
+     * @brief Retrieve a card back pixmap for the loading-in-progress state.
+     * @param pixmap Reference to QPixmap where result will be stored.
+     * @param size Desired size of pixmap.
+     */
     static void getCardBackLoadingInProgressPixmap(QPixmap &pixmap, QSize size);
+
+    /**
+     * @brief Retrieve a card back pixmap for the loading-failed state.
+     * @param pixmap Reference to QPixmap where result will be stored.
+     * @param size Desired size of pixmap.
+     */
     static void getCardBackLoadingFailedPixmap(QPixmap &pixmap, QSize size);
-    static void clearPixmapCache();
+
+    /**
+     * @brief Preload a list of cards into the pixmap cache (limited to CACHED_CARD_PER_DECK_MAX).
+     * @param cards List of ExactCard objects to preload.
+     */
     static void cacheCardPixmaps(const QList<ExactCard> &cards);
+
+    /**
+     * @brief Check if the user has custom card art in the picsPath directory.
+     * @return True if any custom art exists.
+     */
     static bool hasCustomArt();
 
+    /**
+     * @brief Clears the in-memory QPixmap cache for all cards.
+     */
+    static void clearPixmapCache();
+
 public slots:
+    /**
+     * @brief Clears the network disk cache of the worker.
+     */
     static void clearNetworkCache();
 
-private slots:
-    void picDownloadChanged();
-    void picsPathChanged();
-
-public slots:
+    /**
+     * @brief Slot called by the worker when an image is loaded.
+     * Inserts the pixmap into the cache and emits pixmap updated signals.
+     * @param card ExactCard that was loaded.
+     * @param image Loaded QImage.
+     */
     void imageLoaded(const ExactCard &card, const QImage &image);
+
+private slots:
+    /**
+     * @brief Triggered when the user changes the picture download settings.
+     * Clears the QPixmap cache to reload images.
+     */
+    void picDownloadChanged();
+
+    /**
+     * @brief Triggered when the pictures path changes.
+     * Clears the QPixmap cache to reload images.
+     */
+    void picsPathChanged();
 };
+
 #endif