From 60c8e141120741a248e4c58581394fb9af8a3d24 Mon Sep 17 00:00:00 2001
From: AI-scor <354880559+AI-scor@users.noreply.github.com>
Date: Tue, 10 Nov 2026 15:41:01 +0100
Subject: [PATCH] [Docs] Document MoxfieldJsonParser::parse (#7874)

---
 .../parsers/interface_json_deck_parser.h      | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/cockatrice/src/client/network/parsers/interface_json_deck_parser.h b/cockatrice/src/client/network/parsers/interface_json_deck_parser.h
index 7e15d472f..021e98918 100644
--- a/cockatrice/src/client/network/parsers/interface_json_deck_parser.h
+++ b/cockatrice/src/client/network/parsers/interface_json_deck_parser.h
@@ -70,6 +70,25 @@ public:
 class MoxfieldJsonParser : public IJsonDeckParser
 {
 public:
+    /**
+     * @brief Builds a deck list from the JSON that Moxfield's export endpoint returns.
+     *
+     * The boards are keyed by card id, and each entry nests the actual card under
+     * `card` with its name, set and collector number. The mainboard and sideboard
+     * are flattened back into the plain-text deck format and handed to
+     * loadFromStream_Plain, so the normal loader still applies its rules: a blank
+     * line ends the mainboard, and card names are normalized on the way in.
+     *
+     * The name and description are set after the load because loading without
+     * metadata clears them, and provider ids are resolved afterwards against the
+     * card database.
+     *
+     * `commanders` become the banner card and are also added to the main zone,
+     * because a commander is a playable card. `signatureSpells` are added to the
+     * main zone too, but deliberately do not replace the banner card. A
+     * signature spell with no name or a non-positive quantity is skipped instead
+     * of failing the import.
+     */
     DeckList parse(const QJsonObject &obj) override
     {
         DeckList deckList;