From c0be957597b6314b49946e1a4a796f8b601a81ac Mon Sep 17 00:00:00 2001
From: RickyRister <ricky.rister.wang@gmail.com>
Date: Thu, 1 Jan 2026 22:33:08 -0800
Subject: [PATCH] add docs

---
 .../src/interface/deck_loader/deck_loader.cpp |  4 ++
 .../src/interface/deck_loader/deck_loader.h   | 50 +++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/cockatrice/src/interface/deck_loader/deck_loader.cpp b/cockatrice/src/interface/deck_loader/deck_loader.cpp
index 3c93969af..305cd34d9 100644
--- a/cockatrice/src/interface/deck_loader/deck_loader.cpp
+++ b/cockatrice/src/interface/deck_loader/deck_loader.cpp
@@ -158,6 +158,10 @@ bool DeckLoader::saveToNewFile(LoadedDeck &deck, const QString &fileName, DeckFi
     return infoOpt.has_value();
 }
 
+/**
+ * @brief Updates the lastLoadedTimestamp field in the file corresponding to the deck, without changing the
+ * FileModificationTime of the file.
+ */
 bool DeckLoader::updateLastLoadedTimestamp(LoadedDeck &deck)
 {
     QString fileName = deck.lastLoadInfo.fileName;
diff --git a/cockatrice/src/interface/deck_loader/deck_loader.h b/cockatrice/src/interface/deck_loader/deck_loader.h
index 9f79390bd..4d3d38900 100644
--- a/cockatrice/src/interface/deck_loader/deck_loader.h
+++ b/cockatrice/src/interface/deck_loader/deck_loader.h
@@ -52,15 +52,59 @@ public:
         return loadedDeck.lastLoadInfo.isEmpty();
     }
 
+    /**
+     * @brief Asynchronously loads a deck from a local file into this DeckLoader.
+     * The `loadFinished` signal will be emitted when the load finishes.
+     * Once the loading finishes, the deck can be accessed with `getDeck`
+     * @param fileName The file to load
+     * @param fmt The format of the file to load
+     * @param userRequest Whether the load was manually requested by the user, instead of being done in the background.
+     */
     void loadFromFileAsync(const QString &fileName, DeckFileFormat::Format fmt, bool userRequest);
 
+    /**
+     * @brief Loads a deck from a local file.
+     * @param fileName The file to load
+     * @param fmt The format of the file to load
+     * @param userRequest Whether the load was manually requested by the user, instead of being done in the background.
+     * @return An optional containing the LoadedDeck, or empty if the load failed.
+     */
     static std::optional<LoadedDeck>
     loadFromFile(const QString &fileName, DeckFileFormat::Format fmt, bool userRequest = false);
+
+    /**
+     * @brief Loads a deck from the response of a remote deck request
+     * @param nativeString The deck string, in cod format
+     * @param remoteDeckId The remote deck id
+     * @return An optional containing the LoadedDeck, or empty if the load failed.
+     */
     static std::optional<LoadedDeck> loadFromRemote(const QString &nativeString, int remoteDeckId);
 
+    /**
+     * @brief Saves a DeckList to a local file.
+     * @param deck The DeckList
+     * @param fileName The file to write to
+     * @param fmt The deck file format to use
+     * @return An optional containing the LoadInfo for the new file, or empty if the save failed.
+     */
     static std::optional<LoadedDeck::LoadInfo>
     saveToFile(const DeckList &deck, const QString &fileName, DeckFileFormat::Format fmt);
+
+    /**
+     * @brief Saves a LoadedDeck a local file.
+     * Uses the lastLoadInfo in the LoadedDeck to determine where to save to.
+     * @param deck The LoadedDeck to save. Should have valid lastLoadInfo.
+     * @return Whether the save succeeded.
+     */
     static bool saveToFile(const LoadedDeck &deck);
+
+    /**
+     * @brief Saves a LoadedDeck to a new local file.
+     * @param deck The LoadedDeck to save. Will update the lastLoadInfo.
+     * @param fileName The file to write to
+     * @param fmt The deck file format to use
+     * @return Whether the save succeeded.
+     */
     static bool saveToNewFile(LoadedDeck &deck, const QString &fileName, DeckFileFormat::Format fmt);
 
     static QString exportDeckToDecklist(const DeckList &deckList, DecklistWebsite website);
@@ -78,6 +122,12 @@ public:
      */
     static void printDeckList(QPrinter *printer, const DeckList &deckList);
 
+    /**
+     * Converts the given deck's file to the cockatrice file format, using the lastLoadInfo to determine the current
+     * file format and where to write to.
+     * @param deck The deck to convert. Should have valid lastLoadInfo. Will update the lastLoadInfo.
+     * @return Whether the conversion succeeded.
+     */
     static bool convertToCockatriceFormat(LoadedDeck &deck);
 
     LoadedDeck &getDeck()