[Doxygen] More extra-pages for cards/developer documentation and various fixes (#6316)

* Docu stash

Took 1 hour 53 minutes

Took 5 minutes


Took 16 seconds

Took 33 seconds

* Remove file headers.

Took 8 minutes

* Group to card set.

Took 8 seconds

* More extra pages.

Took 28 seconds

* Small fix for now.

Took 3 minutes

* Expand on picture loading.

Took 44 minutes

* Fix line break breaking link.

Took 2 minutes

* Images and user documentation.

Took 1 hour 49 minutes

* Update doc/doxygen-extra-pages/developer_documentation/primer_cards.md

Co-authored-by: RickyRister <42636155+RickyRister@users.noreply.github.com>

---------

Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>
Co-authored-by: RickyRister <42636155+RickyRister@users.noreply.github.com>

Doxyfile

@@ -991,7 +991,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = cockatrice doc/doxygen-groups libcockatrice_card libcockatrice_deck_list libcockatrice_filters libcockatrice_interfaces libcockatrice_models libcockatrice_network libcockatrice_protocol libcockatrice_rng libcockatrice_settings libcockatrice_utility
+INPUT                  = cockatrice doc/doxygen-extra-pages doc/doxygen-groups libcockatrice_card libcockatrice_deck_list libcockatrice_filters libcockatrice_interfaces libcockatrice_models libcockatrice_network libcockatrice_protocol libcockatrice_rng libcockatrice_settings libcockatrice_utility
 
 # This tag can be used to specify the character encoding of the source files
 # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1145,7 +1145,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = doc/doxygen-images
 
 # The INPUT_FILTER tag can be used to specify a program that Doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program

doc/doxygen-extra-pages/developer_documentation/card_database_schema_and_parsing.md

@@ -0,0 +1 @@
+@page card_database_schema_and_parsing Card Database Schema and Parsing

doc/doxygen-extra-pages/developer_documentation/displaying_cards.md

@@ -0,0 +1,83 @@
+@page displaying_cards Displaying Cards
+
+Cockatrice offers a number of widgets for displaying cards. To pick the right one for your purpose, it is first
+important
+to determine the context in which you will be displaying the card.
+
+# In-client
+
+In the client (like in your custom widgets), you can use the existing card display widgets.
+
+## Simple Display
+
+The most general purpose of these is @ref CardInfoPictureWidget, which simply displays a picture of a card.
+
+The textual equivalent to this is @ref CardInfoTextWidget, which displays all the properties of a card in text form.
+
+## Detailed Display
+
+The convenience class @ref CardInfoDisplayWidget displays both of these widgets in a tabbed container, which allows
+choosing between either visual, textual, or both representations at the same time. It is the class that is most
+familiar to our users when a single card is highlighted or inspected, since it is used in the deck editor and in-game
+for these purposes.
+
+If you would like the user to be able to inspect a single card in your custom widget, you should
+expose a @ref CardInfoDisplayWidget to them and incorporate it as a dock widget inside your custom widget.
+
+@ref CardInfoDisplayWidget is great for ensuring that the user has all the relevant details of a card available.
+It is crucial anywhere the user might encounter a card for the first time or needs to make an informed decision.
+
+## Visual Display
+
+However, there is a reason why it is possible to have a visual-only representation of the card in the
+@ref CardInfoDisplayWidget.
+
+Cards are, by design, meant to be represented as images and cards which we can reasonably
+expect the user to know (for example, cards contained in a user made deck or explicitly chosen by the user) can be
+represented with just their image as a sort of "visual shorthand".
+
+The simplest way to do this is of course, the above-mentioned @ref CardInfoPictureWidget which simply displays the
+picture without modifications.
+
+However, there exist a couple of other convenience classes which subclass @ref CardInfoPictureWidget to accomplish some
+things which you might find useful as well.
+
+- @ref CardInfoPictureWithTextOverlayWidget displays text overlaid on top of the card picture and scales this text to
+  fit automatically.
+- @ref DeckPreviewCardPictureWidget is a @ref CardInfoPictureWithTextOverlayWidget which also features a
+  raise-on-mouse-enter animation, controlled by the global setting (TODO: specify which).
+- @ref CardInfoPictureArtCropWidget attempts to display an 'art crop' of the card by cropping the upper region of the
+  card and only displaying that.
+
+## Groups of Cards
+
+Sometimes it is useful to display images of cards in groups, for example to represent the deck in the @ref
+VisualDeckEditorWidget or during confirmation in the pre-game lobby.
+
+To this end, Cockatrice offers three convenience classes to display cards for an index in a @ref DeckListModel in a
+group and one to display all cards in a particular zone of a @ref DeckListModel.
+
+The generic way to do this is @ref CardGroupDisplayWidget, which displays cards in @ref QVBoxLayout. This class is very
+generic and it is probably a better choice to either subclass it or use one of the two existing implementations.
+
+@ref FlatCardGroupDisplayWidget displays cards using a horizontal @ref FlowWidget. This means it will fill available
+screen space, left to right with no margins, with card pictures, skipping to a new line if it overflows available screen
+space horizontally.
+
+@ref OverlappedCardGroupDisplayWidget displays cards using an @ref OverlapWidget, which displays widgets on top of each
+other in vertical columns until it exceeds available screen space in which case it will start a new column. The amount
+of overlap as well as the overlap direction is configurable.
+
+@ref DeckCardZoneDisplayWidget can be used to visualize all cards in a zone with either a @ref
+FlatCardGroupDisplayWidget or a @ref OverlappedCardGroupDisplayWidget and headed by a @ref BannerWidget. It also allows
+grouping and sorting.
+
+# In-game
+
+The in-game view is a @ref QGraphicsScene, which means any widget we want to display inside of it should be a @ref
+QGraphicsObject.
+
+- @ref CardItem
+
+
+

doc/doxygen-extra-pages/developer_documentation/index.md

@@ -1,3 +1,9 @@
 @page developer_reference Developer Reference
 
-- [Contributing](@subpage contributing)
+- @subpage primer_cards
+
+- @subpage card_database_schema_and_parsing
+- @subpage querying_the_card_database
+
+- @subpage loading_card_pictures
+- @subpage displaying_cards

doc/doxygen-extra-pages/developer_documentation/loading_card_pictures.md

@@ -0,0 +1,52 @@
+@page loading_card_pictures Loading Card Pictures
+
+Pictures associated with CardInfo%s are retrieved either from on-disk or the network through the CardPictureLoader.
+
+In most cases, you don't need to concern yourself with the internals of CardPictureLoader.
+
+Simply using one of the ways described in @ref displaying_cards is enough to automatically queue a request to the
+CardPictureLoader when the chosen widget is shown, emitting signals to refresh the widget when the request is finished.
+
+# How requests are triggered
+
+CardPictureLoader::getPixmap() is called exactly two times in the code base, in CardInfoPictureWidget::loadPixmap(), the
+base class
+for all widget based card picture display, and AbstractCardItem::paintPicture(), the base class for all QGraphicsItem
+based card picture
+display. See @ref displaying_cards for more information on the difference between these two display methods.
+
+Because both of these calls are made in the paintEvent() methods of their respective classes, this means that requests
+are issued as soon as but not before the widget is shown on screen.
+
+It is also possible to "warm up" the cache by issuing card picture load requests to the CardPictureLoader without using
+a display widget and waiting for it to be shown by calling CardPictureLoader::cacheCardPixmaps() with a list of
+ExactCard%s.
+
+# The QPixmapCache and QNetworkDiskCache
+
+Cockatrice uses the QPixmapCache from the Qt GUI module to store card pictures in-memory and the QNetworkDiskCache from
+the Qt Network module to cache network requests for card pictures on-disk.
+
+What this means is that the CardPictureLoader will first attempt to look up a card in the QPixmapCache according to the
+ExactCard::getPixmapCacheKey() method of an ExactCard object. If it does not find it in the in-memory cache, it will
+issue a load request, which will first look for local images on-disk and then consult the QNetworkDiskCache and if
+found, use the stored binary data from the network cache to populate the in-memory pixmap cache under the card's cache
+key. If it is not found, it will then proceed with issuing a network request.
+
+The size of both of these caches can be configured by the user in the "Card Sources" settings page.
+
+# PixmapCacheKeys and ProviderIDs
+
+TODO
+
+# The Redirect Cache
+
+TODO
+
+# Local Image Loading
+
+TODO
+
+# URL Generation and Resolution
+
+TODO

doc/doxygen-extra-pages/developer_documentation/primer_cards.md

@@ -0,0 +1,71 @@
+@page primer_cards A Primer on Cards
+
+# The Cockatrice Card Library
+
+All non-gui code related to cards used by Cockatrice is contained within libcockatrice_card.
+
+# A Basic Card Object: CardInfo
+
+A CardInfo object is the translational unit used by the CardDatabase to represent an on-disk XML entry as an in-memory
+Qt object.
+
+For a complete overview of the fields that define a CardInfo object, see the class documentation and more specifically
+@ref PrivateCardProperties.
+
+These fields correspond to either entries or a combination of entries in the XML card entry to which the
+CardDatabaseParser applies special logic to map, populate or determine their respective values in the CardInfo object.
+
+Any property to which special parsing is not applied is stored in CardInfo::properties and may be retrieved or set with
+CardInfo::getProperty() or CardInfo::setProperty() as well as CardInfo::getProperties() to get a collection of the
+property keys a CardInfo contains.
+
+For more information on how special fields contained within @ref PrivateCardProperties are parsed, see
+CockatriceXml4Parser::loadCardsFromXml().
+
+Apart from access to the basic and extended properties of a card, CardInfo also provides two important mechanisms to us.
+The first is the CardInfo::pixmapUpdated() signal, which allows the CardPictureLoader to signal when it is done
+manipulating (in most cases: loading) the QPixmap of an ExactCard::getPixmapCacheKey(), where the ExactCard::card
+corresponds to this CardInfo object.
+
+Put simply: Whenever the CardPictureLoader loads a new PrintingInfo which is not already in the cache, it emits this
+signal so that any widget using a CardInfo object can update the display of it to possibly use this new QPixmap.
+
+\attention It should be noted that it is not possible to use CardPictureLoader::getPixmap() with anything but an
+ExactCard, which is a CardInfo object associated with a PrintingInfo, i.e. a definitive printing of a specific card
+
+The other signal, CardInfo::cardInfoChanged() conceptually works much the same way, except it is concerned with the
+properties of the CardInfo object.
+
+# Getting specific: PrintingInfo and ExactCard
+
+## Printing Info
+
+A CardInfo object describes the basic properties of a card in much the same way that we say "Two cards with the same
+name are and should be equal if their properties are equal". However, there are certain (mostly visual) properties which
+might differ between printings of a card but still conceptually classify two instances of a card as "the same card".
+The most obvious example to this are cards which fundamentally share all properties except the artwork depicted on the
+card.
+
+We refer to such differences as Printings and track them in the PrintingInfo class. A PrintingInfo is always related to
+the CardSet that introduced the variation. Multiple variations can exist in the same CardSet and the respective
+PrintingInfo::getProperty() can be used to determine the differences, such as the collector numbers on the printings, if
+there are any.
+
+## Exact Card
+
+A CardInfo object is used to hold the functional properties of a card and a PrintingInfo object can be used to hold the
+visual properties of a card. To represent a 'physical' card, as in, a concrete immutable instance of a card, we can use
+ExactCard, which combines a CardInfo and a PrintingInfo object into one class. The class is used as a container around
+CardInfo objects whenever the user (and thus the program) expects to be presented with a defined card printing.
+
+# Using Cards
+
+For more information on the XML database schema which the CardDatabaseParser parses to generate CardInfo objects, see
+@ref card_database_schema_and_parsing.
+
+For more information on querying the CardDatabase for CardInfo objects, see @ref querying_the_card_database.
+
+For more information on displaying CardInfo and ExactCard objects using Qt Widgets, see @ref displaying_cards.
+
+For more information on how card pictures are loaded from disk or the network, see @ref loading_card_pictures as well as
+the CardPictureLoader documentation.

doc/doxygen-extra-pages/developer_documentation/querying_the_card_database.md

@@ -0,0 +1,39 @@
+@page querying_the_card_database Querying the Card Database
+
+# The CardDatabaseQuerier Class
+
+The CardDatabaseQuerier is the only class used for querying the database. The CardDatabase is an in-memory map and thus
+provides no structured query language. CardDatabaseQuerier offers methods to retrieve cards by name, by providerID or in
+bulk, as CardSet%s.
+
+## Obtaining a handle to the CardDatabaseQuerier for usage
+
+To obtain the CardDatabaseQuerier related to the global CardDatabase singleton, use CardDatabaseManager::query().
+
+## Querying for known cards
+
+There are, essentially, two ways to ensure card equality, with the second being optional but necessitating the first.
+These two ways are CardInfo name equality and PrintingInfo provider ID equality.
+
+Because of this, most queries require, at the very least, a card name to match against and optionally a providerID to
+narrow the results.
+
+### Generic Card Infos
+
+To check if a card with the exact provided name exists as a CardInfo in the CardDatabase use,
+CardDatabaseQuerier::getCardInfo() or CardDatabaseQuerier::getCardInfos() for multiple cards.
+
+### Guessing Cards
+
+If the exact name might not be present in the CardDatabase, you can use CardDatabaseQuerier::getCardBySimpleName(),
+which automatically simplifies the card name and matches it against simplified card names in the CardDatabase.
+
+Alternatively, you can use CardDatabaseQuerier::lookupCardByName(), which first attempts an exact match search and then
+uses CardDatabaseQuerier::getCardBySimpleName() as a fallback.
+
+### ExactCard%s
+
+To obtain an ExactCard from the CardDatabaseQuerier, you must use a CardRef as a parameter to
+CardDatabaseQuerier::getCard(), CardDatabaseQuerier::getCards(), or CardDatabaseQuerier::guessCard().
+
+CardRef is a simple struct consisting of a card name and a card provider ID as QString%s.

doc/doxygen-extra-pages/user_documentation/deck_management/creating_decks.md

@@ -0,0 +1,17 @@
+@page creating_decks Creating Decks
+
+Creating a new deck is done using either the TabDeckEditor or TabDeckEditorVisual.
+
+They can be accessed either by clicking the "Create Deck" button in the TabHome screen, which will open the default deck
+editor configured in the "User Interface" -> "Deck editor/storage settings" -> "Default deck editor type" setting, or
+by selecting "Deck Editor" or "Visual Deck Editor" under the "Tabs" application menu located at the top.
+
+# Further References
+
+See @ref editing_decks for information on how to modify the attributes and contents of a deck in the Deck Editor
+widgets.
+
+See @ref exporting_decks for information on how to store and persist your deck either in-client or to external
+services.
+
+See @ref importing_decks for information on how to import existing decks either in-client or from external services

doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks.md

@@ -0,0 +1,5 @@
+@page editing_decks Editing Decks
+
+@subpage editing_decks_classic
+
+@subpage editing_decks_visual

doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_classic.md

@@ -0,0 +1,54 @@
+@page editing_decks_classic Classic Deck Editor
+
+\image html classic_deck_editor.png width=900px
+
+# Editing Basic Deck Information
+
+Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
+
+\image html deckeditordeckdockwidget.png
+
+This widget allows editing:
+
+- The name
+- The comments
+- The banner card, which is used to represent the deck in the visual deck storage
+- The tags, which are used for filtering in the visual deck storage
+
+# Adding Cards
+
+Adding cards is done using the list of cards in the database presented in the list view on the left.
+
+\image html classic_database_display.png
+
+Cards can be added by either double-clicking an entry, pressing return with an entry selected to add it to the mainboard
+or pressing ctrl/cmd + return to add it to the sideboard.
+
+There are also buttons for these two functions on the right of the search bar above the list view.
+
+\image html classic_database_display_add_buttons.png
+
+# Modifying the Deck List
+
+To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
+
+\image html deck_dock_deck_list.png
+
+Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
+
+- Increment Card
+- Decrement Card
+- Remove Card
+- Switch Card between Mainboard and Sideboard
+
+\image html deck_dock_deck_list_buttons.png
+
+Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
+display. This is only for visual display and does not affect how the list is saved.
+
+\image html deck_dock_deck_list_group_by.png
+
+# Modifying printings
+
+For more information on modifying the printings in a deck see @ref editing_decks_printings
+

doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_printings.md

@@ -0,0 +1 @@
+@page editing_decks_printings Printing Selector

doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_visual.md

@@ -0,0 +1,71 @@
+@page editing_decks_visual Visual Deck Editor
+
+# Editing Basic Deck Information
+
+Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget).
+
+\image html deckeditordeckdockwidget.png
+
+This widget allows editing:
+
+- The name
+- The comments
+- The banner card, which is used to represent the deck in the visual deck storage
+- The tags, which are used for filtering in the visual deck storage
+
+# Adding Cards
+
+Adding cards is done by either using the "Quick search and add card" search bar at the top of the "Visual Deck View" tab
+or by clicking on a picture of a card in the "Visual Database Display" tab.
+
+See @ref visual_database_display for more information on how to utilize the visual database display.
+
+# Modifying the Deck List
+
+To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used.
+
+Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s):
+
+- Increment Card
+- Decrement Card
+- Remove Card
+- Switch Card between Mainboard and Sideboard
+
+Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list
+display. This is only for visual display and does not affect how the list is saved.
+
+# Modifying the visual deck layout
+
+The visual deck editor displays cards visually, as opposed to simply in list form in the Deck Dock Widget. Each entry in
+the deck list is represented by a picture. These entries are grouped together under their respective sub-groups.
+Sub-groups may be collapsed (i.e. the pictures contained within them are hidden) by clicking on the name of the group in
+the banner.
+
+Cards may either be displayed in a "Flat" layout, which displays each picture next to each other and ensures full
+visibility for each card, or in an "Overlap" layout, which overlaps cards on top of each other (leaving the top 20% of
+the card uncovered so names remain readable) and arranges them in stacks to save space and allow for an easy overview.
+
+Additionally, it is possible to change how the cards in the deck list are grouped by selecting a different grouping
+method from the combo box, either in the top left of the "Visual Deck View" tab or above the list view in the deck dock
+widget.
+
+Furthermore, it is possible to change how the cards are sorted within the sub-group. This is done by clicking on the
+button with the cogwheel icon next to the combo box that adjusts grouping in the top left of the "Visual Deck View" tab.
+This presents a list of available sort criteria, which may be rearranged to change their priorities.
+
+# Modifying printings
+
+For more information on modifying the printings in a deck see @ref editing_decks_printings
+
+# Deck Analytics
+
+The visual deck editor offers a "Deck Analytics" tab, which displays information about:
+
+- The mana curve
+- The mana devotion
+- The mana base
+
+# Sample Hand
+
+The visual deck editor offers a "Sample Hand" tab, which allows simulating drawing a configurable amount of cards from
+the deck, which reduces the need to launch a single player game for testing purposes.

doc/doxygen-extra-pages/user_documentation/deck_management/exporting_decks.md

@@ -0,0 +1,95 @@
+@page exporting_decks Exporting Decks
+
+# Where to export?
+
+There are two screens in the client which can be used to import decks, depending on the context.
+
+- The deck editor tab
+- The deck storage tab (not to be confused with the visual deck storage tab)
+
+# The Deck Editor Tab
+
+The deck editor tabs (Classic and Visual) offer three ways of export a deck:
+
+- To a file on your local storage
+- To your clipboard
+- To an online service
+
+## Local File Storage
+
+To save a deck to a file on your local storage, select the "Save Deck" action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + S
+to access this action.
+
+Selecting this action will open a file picker dialog provided by your operating system. Simply enter a file name and
+select a format (.cod is recommended) and confirm.
+
+Just below the "Save Deck" action described above is the "Save Deck as..." option, which allows saving an existing file
+under a different filename, which is useful for saving a different version or copy of a deck.
+
+## From Clipboard
+
+To save a deck to your clipboard, select the "Save deck to clipboard..." action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
+Shift + C or Ctrl/Cmd + Shift + R to access this action.
+
+Selecting this action will save the currently open deck list to your clipboard.
+
+Saving the decklist without annotations will export the decklist, with each card being described in the following format
+
+```
+CARD_AMOUNT CARD_NAME (SET_SHORT_NAME) CARD_COLLECTOR_NUMBER
+```
+
+There is also the (no set info) option, which will simply export each card as
+
+```
+CARD_AMOUNT CARD_NAME
+```
+
+Mainboard and sideboard are delimited by a newline like so:
+
+```
+1 MainboardCard
+1 OtherMainboardCard
+
+1 SideboardCard
+```
+
+Saving the decklist as annotated will insert comments (marked with // in front of them).
+It will first insert the name and any comments associated with the deck before separating each deck section into its own
+newline delimited and annotated group.
+
+Example: TODO: Adjust this to be non mtg based.
+
+```
+// Deck Name
+
+// Deck Comment
+
+// 10 Maindeck
+// 6 Artifact
+2 The Darkness Crystal (FIN) 335
+2 The Fire Crystal (FIN) 337
+2 Black Mage's Rod (FIN) 90
+
+// 6 Sorcery
+2 Nibelheim Aflame (FIN) 339
+4 Cornered by Black Mages (FIN) 93
+
+// 6 Sideboard
+// 6 Creature
+SB: 4 Blazing Bomb (FIN) 130
+SB: 1 Garland, Knight of Cornelia (FIN) 221
+SB: 1 Undercity Dire Rat (FIN) 123
+```
+
+## From an online service
+
+To export a deck to an online service, select the "Send deck to online service..." action in the "Deck Editor" or "
+Visual Deck Editor" menu in the application menu bar at the top of the screen.
+
+Selecting this action will open your browser with the selected service open and the deck list information from the
+client supplied to it.
+
+Currently supported services are DeckList and TappedOut.

doc/doxygen-extra-pages/user_documentation/deck_management/importing_decks.md

@@ -0,0 +1,62 @@
+@page importing_decks Importing Decks
+
+# Where to import?
+
+There are three screens in the client which can be used to import decks, depending on the context.
+
+- The deck editor tab
+- The pre-game lobby tab
+- The deck storage tab (not to be confused with the visual deck storage tab)
+
+# The Deck Editor Tab
+
+The deck editor tabs (Classic and Visual) offer three ways of importing a deck:
+
+- From a file on your local storage
+- From your clipboard
+- From an online service
+
+## Local File Storage
+
+To load a deck from a file on your local storage, select the "Load Deck" action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + O
+to access this action.
+
+Selecting this action will open a file picker dialog provided by your operating system. Simply select a supported file
+here and it will be loaded.
+
+Just below the "Load Deck" action described above is the "Load recent deck" option, which keeps a record of the last 10
+loaded decks for quick access.
+
+## From Clipboard
+
+To load a deck from your clipboard, select the "Load deck from clipboard..." action in the "Deck Editor" or "Visual Deck
+Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd +
+Shift + V to access this action.
+
+Selecting this action will open a new text editor dialog with the contents of your clipboard pasted inside it.
+
+The import dialog expects each line to be a card with the following format:
+
+TODO
+
+Each card should be on a separate line and there should be no empty lines between cards. The first empty line between
+two blocks of cards will be considered as the divider between mainboard and sideboard.
+
+Selecting "Parse Set Name and Number (if available)" will automatically parse these options and attempt to resolve them
+to valid provider IDs found in the card database. If this option is unselected, Cockatrice will import all cards as
+versions without provider IDs, which means they will display to everyone according to their own user defined set
+preferences, rather than being the same defined printing for everyone.
+
+## From an online service
+
+To load a deck from an online service, select the "Load deck from online service..." action in the "Deck Editor" or "
+Visual Deck Editor" menu in the application menu bar at the top of the screen.
+
+Selecting this action will open a dialog containing the contents of your clipboard pasted into it. If your clipboard
+currently contains a supported URL, the dialog will accept it and close on its own, otherwise you may adjust the URL and
+confirm.
+
+The action will automatically import the deck from the online service without any other required user action.
+
+Currently supported services are Archidekt, Deckstats, Moxfield, and TappedOut.

doc/doxygen-extra-pages/user_documentation/index.md

@@ -1,4 +1,13 @@
 @page user_reference User Reference
 
 @subpage search_syntax_help
-@subpage deck_search_syntax_help
+
+@subpage deck_search_syntax_help
+
+@subpage creating_decks
+
+@subpage importing_decks
+
+@subpage editing_decks
+
+@subpage exporting_decks

libcockatrice_card/libcockatrice/card/card_info.h

@@ -1,9 +1,3 @@
-/**
- * @file card_info.h
- * @ingroup Cards
- * @brief TODO: Document this.
- */
-
 #ifndef CARD_INFO_H
 #define CARD_INFO_H
 
@@ -54,6 +48,10 @@ class CardInfo : public QObject
     Q_OBJECT
 
 private:
+    /** @name Private Card Properties
+     *  @anchor PrivateCardProperties
+     */
+    ///@{
     CardInfoPtr smartThis;                         ///< Smart pointer to self for safe cross-references.
     QString name;                                  ///< Full name of the card.
     QString simpleName;                            ///< Simplified name for fuzzy matching.
@@ -69,6 +67,7 @@ private:
     bool landscapeOrientation;                     ///< Orientation flag for rendering.
     int tableRow;                                  ///< Row index in a table or visual representation.
     bool upsideDownArt;                            ///< Whether artwork is flipped for visual purposes.
+    ///@}
 
 public:
     /**

libcockatrice_card/libcockatrice/card/database/card_database.h

@@ -1,10 +1,3 @@
-/**
- * @file card_database.h
- * @ingroup CardDatabase
- * @brief The CardDatabase is responsible for holding the card and set maps, managing card additions/removals,
- * and providing access to sets and card querying via CardDatabaseQuerier.
- */
-
 #ifndef CARDDATABASE_H
 #define CARDDATABASE_H
 

libcockatrice_card/libcockatrice/card/database/card_database_loader.h

@@ -1,12 +1,3 @@
-/**
- * @file card_database_loader.h
- * @ingroup CardDatabase
- * @brief The CardDatabaseLoader is responsible for discovering, loading, and saving card databases from files on disk.
- *
- * This class interacts with available parsers to populate a CardDatabase instance. It also handles
- * loading main, token, spoiler, and custom card databases.
- */
-
 #ifndef COCKATRICE_CARD_DATABASE_LOADER_H
 #define COCKATRICE_CARD_DATABASE_LOADER_H
 

libcockatrice_card/libcockatrice/card/printing/exact_card.h

@@ -5,7 +5,7 @@
 
 /**
  * @class ExactCard
- * @ingroup Cards
+ * @ingroup CardPrintings
  *
  * @brief Represents a specific card instance, defined by its CardInfo
  *        and a particular printing.

libcockatrice_card/libcockatrice/card/printing/printing_info.h

@@ -14,7 +14,7 @@ using SetToPrintingsMap = QMap<QString, QList<PrintingInfo>>;
 
 /**
  * @class PrintingInfo
- * @ingroup Cards
+ * @ingroup CardPrintings
  *
  * @brief Represents metadata for a specific variation of a card within a set.
  *

libcockatrice_card/libcockatrice/card/set/card_set.h

@@ -15,7 +15,7 @@ using CardSetPtr = QSharedPointer<CardSet>;
 
 /**
  * @class CardSet
- * @ingroup Cards
+ * @ingroup CardSets
  *
  * @brief A collection of cards grouped under a common identifier.
  *

libcockatrice_card/libcockatrice/card/set/card_set_comparator.h

@@ -1,6 +1,6 @@
 /**
  * @file card_set_comparator.h
- * @ingroup Cards
+ * @ingroup CardSets
  * @brief TODO: Document this.
  */
 

libcockatrice_card/libcockatrice/card/set/card_set_list.h

@@ -8,7 +8,7 @@
 
 /**
  * @class CardSetList
- * @ingroup Cards
+ * @ingroup CardSets
  *
  * @brief A list-like container for CardSet objects with extended management methods.
  *