From f361cd65e0b8ded6d3c8b015600cc9e75ad6d1e1 Mon Sep 17 00:00:00 2001 From: DawnFire42 Date: Wed, 13 May 2026 12:56:22 -0400 Subject: [PATCH] Standardize Doxygen documentation style to @brief format MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert leading triple-slash (///) comments to JavaDoc-style (/** @brief */) documentation blocks across game, deck list, and card library modules. - Leading /// comments → /** @brief ... */ - Enum value comments → ///< - Trailing ///< member comments are unchanged --- .../client/settings/shortcuts_settings.cpp | 13 ++-- cockatrice/src/game/card_dimensions.h | 8 +-- cockatrice/src/game/game_scene.h | 40 +++++------ .../player/menu/abstract_player_component.h | 6 +- cockatrice/src/game/player/menu/player_menu.h | 13 ++-- cockatrice/src/game/z_value_layer_manager.h | 9 +-- .../src/game_graphics/zones/card_zone.h | 9 ++- .../src/game_graphics/zones/select_zone.h | 68 ++++++++++++------- .../src/game_graphics/zones/stack_zone.h | 2 +- .../deck_editor_deck_dock_widget.cpp | 2 +- .../widgets/deck_editor/deck_state_manager.h | 8 ++- .../general/display/charts/bars/color_bar.h | 6 +- .../widgets/replay/replay_timeline_widget.cpp | 10 ++- ...pi_response_deck_listings_display_widget.h | 8 +-- .../tab_deck_editor_visual_tab_widget.h | 10 +-- .../visual_deck_display_options_widget.h | 22 +++--- .../card/database/card_database.h | 16 ++--- .../card/database/card_database_manager.h | 6 +- .../libcockatrice/card/set/card_set.h | 16 ++--- .../libcockatrice/deck_list/deck_list.h | 24 ++++--- .../deck_list/deck_list_node_tree.h | 6 +- .../libcockatrice/deck_list/sideboard_plan.h | 6 +- .../tree/abstract_deck_list_card_node.h | 24 +++---- .../deck_list/tree/abstract_deck_list_node.h | 4 +- .../deck_list/tree/deck_list_card_node.h | 26 +++---- .../deck_list/tree/inner_deck_list_node.h | 22 +++--- 26 files changed, 207 insertions(+), 177 deletions(-) diff --git a/cockatrice/src/client/settings/shortcuts_settings.cpp b/cockatrice/src/client/settings/shortcuts_settings.cpp index 53c6f6a23..2ff65ab6f 100644 --- a/cockatrice/src/client/settings/shortcuts_settings.cpp +++ b/cockatrice/src/client/settings/shortcuts_settings.cpp @@ -64,8 +64,13 @@ ShortcutsSettings::ShortcutsSettings(const QString &settingsPath, QObject *paren } } -/// PR 5079 changes Textbox/unfocusTextBox to Player/unfocusTextBox and tab_game/aFocusChat to Player/aFocusChat. -/// A migration is necessary to let players keep their already configured shortcuts. +/** + * @brief Migrates legacy shortcut key names to current naming scheme. + * + * PR 5079 changed Textbox/unfocusTextBox to Player/unfocusTextBox and + * tab_game/aFocusChat to Player/aFocusChat. This migration allows players + * to keep their already configured shortcuts. + */ void ShortcutsSettings::migrateShortcuts() { if (QFile(settingsFilePath).exists()) { @@ -236,9 +241,7 @@ bool ShortcutsSettings::isValid(const QString &name, const QString &sequences) c return findOverlaps(name, sequences).isEmpty(); } -/** - * Checks if the shortcut is a shortcut that is active in all windows - */ +/** @brief Checks if the shortcut is a shortcut that is active in all windows. */ static bool isAlwaysActiveShortcut(const QString &shortcutName) { return shortcutName.startsWith("MainWindow") || shortcutName.startsWith("Tabs"); diff --git a/cockatrice/src/game/card_dimensions.h b/cockatrice/src/game/card_dimensions.h index 255d0bc04..c59a01b48 100644 --- a/cockatrice/src/game/card_dimensions.h +++ b/cockatrice/src/game/card_dimensions.h @@ -12,16 +12,16 @@ */ namespace CardDimensions { -/// Card width in pixels +/** @brief Card width in pixels. */ constexpr int WIDTH = 72; -/// Card height in pixels +/** @brief Card height in pixels. */ constexpr int HEIGHT = 102; -/// Pre-converted for floating-point contexts (Z-value calculations) +/** @brief Pre-converted for floating-point contexts (Z-value calculations). */ constexpr qreal WIDTH_F = static_cast(WIDTH); constexpr qreal HEIGHT_F = static_cast(HEIGHT); -/// Half-dimensions for centering and rotation transforms +/** @brief Half-dimensions for centering and rotation transforms. */ constexpr qreal WIDTH_HALF_F = WIDTH_F / 2; constexpr qreal HEIGHT_HALF_F = HEIGHT_F / 2; } // namespace CardDimensions diff --git a/cockatrice/src/game/game_scene.h b/cockatrice/src/game/game_scene.h index a2d712609..a2b9cdbbd 100644 --- a/cockatrice/src/game/game_scene.h +++ b/cockatrice/src/game/game_scene.h @@ -56,10 +56,12 @@ private: */ void updateHover(const QPointF &scenePos); - /// Activates hover state and escapes the card from its clip container so hover scaling is visible beyond zone - /// bounds. + /** + * @brief Activates hover state and escapes the card from its clip container + * so hover scaling is visible beyond zone bounds. + */ void beginCardHover(CardItem *card); - /// Deactivates hover state and restores the card to its clip container. + /** @brief Deactivates hover state and restores the card to its clip container. */ void endCardHover(CardItem *card); public: @@ -70,13 +72,13 @@ public: */ explicit GameScene(PhasesToolbar *_phasesToolbar, QObject *parent = nullptr); - /** Destructor, cleans up timer and zone views. */ + /** @brief Destructor, cleans up timer and zone views. */ ~GameScene() override; - /** Updates UI text for all zone views. */ + /** @brief Updates UI text for all zone views. */ void retranslateUi(); - /** Gets all selected CardItems */ + /** @brief Gets all selected CardItems. */ QList selectedCards() const; /** @@ -97,7 +99,7 @@ public: */ void adjustPlayerRotation(int rotationAdjustment); - /** Recomputes the layout of players and the scene size. */ + /** @brief Recomputes the layout of players and the scene size. */ void rearrange(); /** @@ -157,50 +159,50 @@ public: */ void resizeColumnsAndPlayers(const QList &minWidthByColumn, qreal newWidth); - /** Finds the topmost card zone under the cursor. */ + /** @brief Finds the topmost card zone under the cursor. */ static CardZone *findTopmostZone(const QList &items); - /** Finds the topmost card in a given zone, considering attachments and Z-order. */ + /** @brief Finds the topmost card in a given zone, considering attachments and Z-order. */ static CardItem *findTopmostCardInZone(const QList &items, CardZone *zone); - /** Updates hovered card highlighting. */ + /** @brief Updates hovered card highlighting. */ void updateHoveredCard(CardItem *newCard); - /** Registers a card for animation updates. */ + /** @brief Registers a card for animation updates. */ void registerAnimationItem(AbstractCardItem *card); - /** Unregisters a card from animation updates. */ + /** @brief Unregisters a card from animation updates. */ void unregisterAnimationItem(AbstractCardItem *card); void startRubberBand(const QPointF &selectionOrigin); void resizeRubberBand(const QPointF &cursorPoint, int selectedCount); void stopRubberBand(); public slots: - /** Toggles a zone view for a player. */ + /** @brief Toggles a zone view for a player. */ void toggleZoneView(PlayerLogic *player, const QString &zoneName, int numberCards, bool isReversed = false); - /** Adds a revealed zone view (for shown cards). */ + /** @brief Adds a revealed zone view (for shown cards). */ void addRevealedZoneView(PlayerLogic *player, CardZoneLogic *zone, const QList &cardList, bool withWritePermission); - /** Removes a zone view widget from the scene. */ + /** @brief Removes a zone view widget from the scene. */ void removeZoneView(ZoneViewWidget *item); - /** Closes all zone views. */ + /** @brief Closes all zone views. */ void clearViews(); - /** Closes the most recently added zone view. */ + /** @brief Closes the most recently added zone view. */ void closeMostRecentZoneView(); QTransform getViewTransform() const; QTransform getViewportTransform() const; protected: - /** Handles hover updates. */ + /** @brief Handles hover updates. */ bool event(QEvent *event) override; - /** Handles animation timer updates. */ + /** @brief Handles animation timer updates. */ void timerEvent(QTimerEvent *event) override; signals: diff --git a/cockatrice/src/game/player/menu/abstract_player_component.h b/cockatrice/src/game/player/menu/abstract_player_component.h index 989300d41..ee310c428 100644 --- a/cockatrice/src/game/player/menu/abstract_player_component.h +++ b/cockatrice/src/game/player/menu/abstract_player_component.h @@ -19,13 +19,13 @@ class AbstractPlayerComponent public: virtual ~AbstractPlayerComponent() = default; - /// Bind keyboard shortcuts. Called when this player gains focus. + /** @brief Bind keyboard shortcuts. Called when this player gains focus. */ virtual void setShortcutsActive() = 0; - /// Unbind keyboard shortcuts. Called when this player loses focus. + /** @brief Unbind keyboard shortcuts. Called when this player loses focus. */ virtual void setShortcutsInactive() = 0; - /// Retranslate all user-visible strings. Called on language change. + /** @brief Retranslate all user-visible strings. Called on language change. */ virtual void retranslateUi() = 0; }; diff --git a/cockatrice/src/game/player/menu/player_menu.h b/cockatrice/src/game/player/menu/player_menu.h index 7532ac225..b441920b5 100644 --- a/cockatrice/src/game/player/menu/player_menu.h +++ b/cockatrice/src/game/player/menu/player_menu.h @@ -38,7 +38,7 @@ private slots: public: explicit PlayerMenu(PlayerLogic *player); - /// Lifecycle methods: delegate to all managedComponents, plus counters separately via player->getCounters(). + /** @brief Retranslate all user-visible strings. Called on language change. */ void retranslateUi(); QMenu *updateCardMenu(const CardItem *card); @@ -68,9 +68,9 @@ public: return shortcutsActive; } - /// Delegates to all managedComponents, plus counters separately. + /** @brief Bind keyboard shortcuts. Called when this player gains focus. */ void setShortcutsActive(); - /// Delegates to all managedComponents, plus counters separately. + /** @brief Unbind keyboard shortcuts. Called when this player loses focus. */ void setShortcutsInactive(); private: @@ -86,11 +86,12 @@ private: SayMenu *sayMenu; CustomZoneMenu *customZonesMenu; - /// Drives AbstractPlayerComponent lifecycle delegation. Counters are iterated separately via player->getCounters(). + /** @brief Drives AbstractPlayerComponent lifecycle delegation. Counters are iterated separately via + * player->getCounters(). */ QList managedComponents; bool shortcutsActive = false; - /// Creates component, adds it as a submenu of playerMenu, and registers in managedComponents. + /** @brief Creates component, adds it as a submenu of playerMenu, and registers in managedComponents. */ template MenuT *addManagedMenu(Args &&...args) { auto *menu = new MenuT(std::forward(args)...); @@ -99,7 +100,7 @@ private: return menu; } - /// Creates component and registers in managedComponents, but does NOT add it as a submenu. + /** @brief Creates component and registers in managedComponents, but does NOT add it as a submenu. */ template ComponentT *createManagedComponent(Args &&...args) { auto *component = new ComponentT(std::forward(args)...); diff --git a/cockatrice/src/game/z_value_layer_manager.h b/cockatrice/src/game/z_value_layer_manager.h index 4eb864486..d35ab5c1c 100644 --- a/cockatrice/src/game/z_value_layer_manager.h +++ b/cockatrice/src/game/z_value_layer_manager.h @@ -66,12 +66,9 @@ namespace ZValueLayerManager */ enum class Layer { - /// Zone-level elements like backgrounds and containers - Zone, - /// Cards rendered in zones (uses sequential Z-values) - Card, - /// Temporary UI elements like hovered cards and drag items - Overlay + Zone, ///< Zone-level elements like backgrounds and containers. + Card, ///< Cards rendered in zones (uses sequential Z-values). + Overlay ///< Temporary UI elements like hovered cards and drag items. }; /** diff --git a/cockatrice/src/game_graphics/zones/card_zone.h b/cockatrice/src/game_graphics/zones/card_zone.h index 80226de3c..4cef6ca80 100644 --- a/cockatrice/src/game_graphics/zones/card_zone.h +++ b/cockatrice/src/game_graphics/zones/card_zone.h @@ -40,9 +40,12 @@ protected: } public slots: bool showContextMenu(const QPoint &screenPos); - /// @brief Called when a card is added to this zone. Default: reparents card to this item. - /// Virtual so subclasses (e.g. SelectZone) can override parenting behavior — the Qt signal - /// connection in CardZone's constructor dispatches through the vtable. + /** + * @brief Called when a card is added to this zone. Default: reparents card to this item. + * + * Virtual so subclasses (e.g. SelectZone) can override parenting behavior — the Qt signal + * connection in CardZone's constructor dispatches through the vtable. + */ virtual void onCardAdded(CardItem *addedCard); public: diff --git a/cockatrice/src/game_graphics/zones/select_zone.h b/cockatrice/src/game_graphics/zones/select_zone.h index 1da5c1988..7408f29b6 100644 --- a/cockatrice/src/game_graphics/zones/select_zone.h +++ b/cockatrice/src/game_graphics/zones/select_zone.h @@ -21,33 +21,41 @@ class SelectZone : public CardZone { Q_OBJECT public: - /// Finds the SelectZone that owns a card, regardless of whether the card is parented - /// to the zone directly or to its clip container. Returns nullptr if not in a SelectZone. + /** + * @brief Finds the SelectZone that owns a card, regardless of whether the card is parented + * to the zone directly or to its clip container. Returns nullptr if not in a SelectZone. + */ static SelectZone *findOwningSelectZone(const QGraphicsItem *card); SelectZone(CardZoneLogic *logic, QGraphicsItem *parent = nullptr); ~SelectZone() override; void onCardAdded(CardItem *addedCard) override; - /// @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip - /// bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no - /// transform). + /** + * @brief Temporarily reparents a card from the clip container to this zone so hover scaling is visible beyond clip + * bounds. Safe no-op if no clip container exists. Coordinates are preserved (clip container is at (0,0) with no + * transform). + */ void escapeClipForHover(QGraphicsItem *card); - /// @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already - /// reparented the card. + /** + * @brief Restores a hover-escaped card back to the clip container. Guards against zone transitions that already + * reparented the card. + */ void restoreClipAfterHover(QGraphicsItem *card); private: QPointF selectionOrigin; QSet cardsInSelectionRect; - /// Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone). - /// Created by setupClipContainer(); null when no clip container is active. + /** + * @brief Invisible clipping parent for cards; owned by Qt parent-child tree (parented to this zone). + * Created by setupClipContainer(); null when no clip container is active. + */ QGraphicsRectItem *cardClipContainer = nullptr; protected: // -- Layout computation -- - /// Parameters describing a vertical card stack's geometry. + /** @brief Parameters describing a vertical card stack's geometry. */ struct StackLayoutParams { int cardCount; ///< Number of cards in the stack @@ -55,21 +63,23 @@ protected: qreal cardHeight; ///< Height of a single card qreal desiredOffset; ///< Preferred vertical offset between card tops qreal minOffset = 0.0; ///< Minimum offset to preserve (0 allows full compression) - /// When false (default), reserves full cardHeight for the bottom card, ensuring - /// all cards remain within zone bounds. When true, allows the bottom card to - /// partially overflow using sqrt-scaled allowance. Use with setupClipContainer() - /// for zones too short to fit a full card. + /** + * @brief When false (default), reserves full cardHeight for the bottom card, ensuring + * all cards remain within zone bounds. When true, allows the bottom card to + * partially overflow using sqrt-scaled allowance. Use with setupClipContainer() + * for zones too short to fit a full card. + */ bool allowBottomOverflow = false; }; - /// Result of computing a vertical stack layout. + /** @brief Result of computing a vertical stack layout. */ struct ZoneLayout { qreal effectiveOffset; ///< Actual offset between card tops (may be compressed) qreal start; ///< Y coordinate of the first card's top edge }; - /// Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones. + /** @brief Minimum visible pixels of each card's top edge when stacking compresses offsets in tight zones. */ static constexpr qreal MIN_CARD_VISIBLE = 10.0; /** @@ -88,11 +98,13 @@ protected: */ static ZoneLayout computeZoneLayout(const StackLayoutParams ¶ms); - /// Builds StackLayoutParams from the current card list and zone geometry. + /** @brief Builds StackLayoutParams from the current card list and zone geometry. */ StackLayoutParams buildStackParams(qreal minOffset = 0.0) const; - /// Computes the card index at a given y-coordinate within the zone's vertical layout. - /// Returns 0 if the zone has no cards or the offset is zero. + /** + * @brief Computes the card index at a given y-coordinate within the zone's vertical layout. + * Returns 0 if the zone has no cards or the offset is zero. + */ int calcDropIndexFromY(qreal dropY, qreal minOffset = 0.0) const; /** @@ -111,17 +123,21 @@ protected: // (e.g., zones too short to fit a full card). To enable: call setupClipContainer() in the // zone's constructor, and set allowBottomOverflow=true in layout params. - /// Restores any cards that were hover-escaped but whose hover state was not properly cleaned up. - /// Call at the start of reorganizeCards() in zones that use a clip container. + /** + * @brief Restores any cards that were hover-escaped but whose hover state was not properly cleaned up. + * Call at the start of reorganizeCards() in zones that use a clip container. + */ void restoreStaleEscapedCards(); - /// Creates a clip container child item that clips card overflow to zone bounds. - /// Cards entering this zone are reparented to this container by the onCardAdded override. - /// Disables zone-level child clipping; clipping is delegated to the container. - /// @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE) + /** + * @brief Creates a clip container child item that clips card overflow to zone bounds. + * Cards entering this zone are reparented to this container by the onCardAdded override. + * Disables zone-level child clipping; clipping is delegated to the container. + * @param zValue Optional z-value for the clip container (e.g. ZValues::CARD_BASE) + */ void setupClipContainer(std::optional zValue = std::nullopt); - /// Updates the clip container rect to match this zone's current boundingRect(). + /** @brief Updates the clip container rect to match this zone's current boundingRect(). */ void updateClipRect(); void mouseMoveEvent(QGraphicsSceneMouseEvent *event) override; diff --git a/cockatrice/src/game_graphics/zones/stack_zone.h b/cockatrice/src/game_graphics/zones/stack_zone.h index ed13ae1f9..147c3e2fc 100644 --- a/cockatrice/src/game_graphics/zones/stack_zone.h +++ b/cockatrice/src/game_graphics/zones/stack_zone.h @@ -20,7 +20,7 @@ private slots: public: StackZone(StackZoneLogic *_logic, int _zoneHeight, QGraphicsItem *parent); - /// @brief Resizes the stack zone height, e.g. when sharing vertical space with the command zone. + /** @brief Resizes the stack zone height, e.g. when sharing vertical space with the command zone. */ void setHeight(qreal newHeight); void handleDropEvent(const QList &dragItems, CardZoneLogic *startZone, const QPoint &dropPoint) override; diff --git a/cockatrice/src/interface/widgets/deck_editor/deck_editor_deck_dock_widget.cpp b/cockatrice/src/interface/widgets/deck_editor/deck_editor_deck_dock_widget.cpp index 25d9db079..a80ba3486 100644 --- a/cockatrice/src/interface/widgets/deck_editor/deck_editor_deck_dock_widget.cpp +++ b/cockatrice/src/interface/widgets/deck_editor/deck_editor_deck_dock_widget.cpp @@ -531,7 +531,7 @@ void DeckEditorDeckDockWidget::changeSelectedCard(int changeBy) // currentIndex will return an index for the underlying deckModel instead of the proxy. // That index will return an invalid index when indexBelow/indexAbove crosses a header node, // causing the selection to fail to move down. - /// \todo Figure out why it's happening so we can do a proper fix instead of a hacky workaround + /** @todo Figure out why it's happening so we can do a proper fix instead of a hacky workaround. */ if (deckViewCurrentIndex.model() == proxy->sourceModel()) { deckViewCurrentIndex = proxy->mapFromSource(deckViewCurrentIndex); } diff --git a/cockatrice/src/interface/widgets/deck_editor/deck_state_manager.h b/cockatrice/src/interface/widgets/deck_editor/deck_state_manager.h index 4f1ec7e04..10312d0a0 100644 --- a/cockatrice/src/interface/widgets/deck_editor/deck_state_manager.h +++ b/cockatrice/src/interface/widgets/deck_editor/deck_state_manager.h @@ -154,9 +154,11 @@ public: */ QModelIndex modifyDeck(const QString &reason, const std::function &operation); - /// @name Metadata setters - /// @brief These methods set the metadata. Will no-op if the new value is the same as the current value. - /// Saves the operation to history if successful. + /** + * @name Metadata setters + * @brief These methods set the metadata. Will no-op if the new value is the same as the current value. + * Saves the operation to history if successful. + */ ///@{ void setName(const QString &name); void setComments(const QString &comments); diff --git a/cockatrice/src/interface/widgets/general/display/charts/bars/color_bar.h b/cockatrice/src/interface/widgets/general/display/charts/bars/color_bar.h index 0ef68f578..100f95310 100644 --- a/cockatrice/src/interface/widgets/general/display/charts/bars/color_bar.h +++ b/cockatrice/src/interface/widgets/general/display/charts/bars/color_bar.h @@ -99,13 +99,13 @@ protected: void mouseMoveEvent(QMouseEvent *event) override; private: - /// Map of color keys to counts used for rendering. + /** @brief Map of color keys to counts used for rendering. */ QList> colors; - /// True if the mouse is currently inside the widget. + /** @brief True if the mouse is currently inside the widget. */ bool isHovered = false; - /// Minimum ratio a segment must exceed to be drawn. + /** @brief Minimum ratio a segment must exceed to be drawn. */ double minRatioThreshold = 0.0; /** diff --git a/cockatrice/src/interface/widgets/replay/replay_timeline_widget.cpp b/cockatrice/src/interface/widgets/replay/replay_timeline_widget.cpp index 508d45666..46a3dff40 100644 --- a/cockatrice/src/interface/widgets/replay/replay_timeline_widget.cpp +++ b/cockatrice/src/interface/widgets/replay/replay_timeline_widget.cpp @@ -103,8 +103,12 @@ void ReplayTimelineWidget::skipToTime(int newTime, bool doRewindBuffering) update(); } -/// @param doRewindBuffering When true, if multiple backward skips are made in quick succession, only a single rewind -/// is processed at the end. When false, the backwards skip will always cause an immediate rewind +/** + * @brief Handles a backwards skip in the replay timeline. + * + * @param doRewindBuffering When true, if multiple backward skips are made in quick succession, only a single rewind + * is processed at the end. When false, the backwards skip will always cause an immediate rewind. + */ void ReplayTimelineWidget::handleBackwardsSkip(bool doRewindBuffering) { if (doRewindBuffering) { @@ -151,7 +155,7 @@ void ReplayTimelineWidget::replayTimerTimeout() } } -/// Processes all unprocessed events up to the current time. +/** @brief Processes all unprocessed events up to the current time. */ void ReplayTimelineWidget::processNewEvents(PlaybackMode playbackMode) { currentProcessedTime = currentVisualTime; diff --git a/cockatrice/src/interface/widgets/tabs/api/archidekt/display/archidekt_api_response_deck_listings_display_widget.h b/cockatrice/src/interface/widgets/tabs/api/archidekt/display/archidekt_api_response_deck_listings_display_widget.h index 479de5fc8..f9a887aa4 100644 --- a/cockatrice/src/interface/widgets/tabs/api/archidekt/display/archidekt_api_response_deck_listings_display_widget.h +++ b/cockatrice/src/interface/widgets/tabs/api/archidekt/display/archidekt_api_response_deck_listings_display_widget.h @@ -82,16 +82,16 @@ public: void resizeEvent(QResizeEvent *event) override; private: - /// Slider controlling the scale of card thumbnails in all deck entry widgets. + /** @brief Slider controlling the scale of card thumbnails in all deck entry widgets. */ CardSizeWidget *cardSizeSlider; - /// Main horizontal layout containing the FlowWidget. + /** @brief Main horizontal layout containing the FlowWidget. */ QHBoxLayout *layout; - /// Container providing scrollable multi-row flow layout of deck entries. + /** @brief Container providing scrollable multi-row flow layout of deck entries. */ FlowWidget *flowWidget; - /// Shared network manager used to download card images for all child entry widgets. + /** @brief Shared network manager used to download card images for all child entry widgets. */ QNetworkAccessManager *imageNetworkManager; }; diff --git a/cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual_tab_widget.h b/cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual_tab_widget.h index 9468df425..48dd8ea9d 100644 --- a/cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual_tab_widget.h +++ b/cockatrice/src/interface/widgets/tabs/visual_deck_editor/tab_deck_editor_visual_tab_widget.h @@ -63,19 +63,19 @@ public: CardDatabaseModel *_cardDatabaseModel, CardDatabaseDisplayModel *_cardDatabaseDisplayModel); - /// Add a new tab with a widget and title. + /** @brief Add a new tab with a widget and title. */ void addNewTab(QWidget *widget, const QString &title); - /// Remove the currently active tab. + /** @brief Remove the currently active tab. */ void removeCurrentTab(); - /// Set the title of a specific tab. + /** @brief Set the title of a specific tab. */ void setTabTitle(int index, const QString &title); - /// Get the currently active tab widget. + /** @brief Get the currently active tab widget. */ [[nodiscard]] QWidget *getCurrentTab() const; - /// Get the total number of tabs. + /** @brief Get the total number of tabs. */ [[nodiscard]] int getTabCount() const; VisualDeckEditorWidget *visualDeckView; ///< Visual deck editor widget. diff --git a/cockatrice/src/interface/widgets/visual_deck_editor/visual_deck_display_options_widget.h b/cockatrice/src/interface/widgets/visual_deck_editor/visual_deck_display_options_widget.h index 9930ff50b..bc11884df 100644 --- a/cockatrice/src/interface/widgets/visual_deck_editor/visual_deck_display_options_widget.h +++ b/cockatrice/src/interface/widgets/visual_deck_editor/visual_deck_display_options_widget.h @@ -104,37 +104,37 @@ private slots: void updateDisplayType(); private: - /// Layout for grouping and sorting UI elements. + /** @brief Layout for grouping and sorting UI elements. */ QHBoxLayout *groupAndSortLayout; - /// Current deck display type. + /** @brief Current deck display type. */ DisplayType currentDisplayType = DisplayType::Overlap; - /// Button used to toggle the display layout. + /** @brief Button used to toggle the display layout. */ CompactPushButton *displayTypeButton; - /// Label for the group-by selector. + /** @brief Label for the group-by selector. */ QLabel *groupByLabel; - /// Combo box listing group-by criteria. + /** @brief Combo box listing group-by criteria. */ QComboBox *groupByComboBox; - /// Currently active group-by criterion. + /** @brief Currently active group-by criterion. */ QString activeGroupCriteria = "maintype"; - /// Encapsulates the sort settings widgets (label + list). + /** @brief Encapsulates the sort settings widgets (label + list). */ SettingsButtonWidget *sortCriteriaButton; - /// Label for “Sort by”. + /** @brief Label for "Sort by". */ QLabel *sortByLabel; - /// Descriptive label inside the sort criteria button. + /** @brief Descriptive label inside the sort criteria button. */ QLabel *sortLabel; - /// Draggable list of sort criteria. + /** @brief Draggable list of sort criteria. */ QListWidget *sortByListWidget; - /// Ordered list of current sort criteria. + /** @brief Ordered list of current sort criteria. */ QStringList activeSortCriteria = {"name", "cmc", "colors", "maintype"}; }; diff --git a/libcockatrice_card/libcockatrice/card/database/card_database.h b/libcockatrice_card/libcockatrice/card/database/card_database.h index b1af3a2c0..d86e2d113 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database.h @@ -30,27 +30,27 @@ class CardDatabase : public QObject Q_OBJECT protected: - /// Controller to determine set priority when choosing preferred printings. + /** @brief Controller to determine set priority when choosing preferred printings. */ ICardSetPriorityController *setPriorityController; - /// Cards indexed by exact name + /** @brief Cards indexed by exact name. */ CardNameMap cards; - /// Cards indexed by simplified name (normalized) + /** @brief Cards indexed by simplified name (normalized). */ CardNameMap simpleNameCards; - /// Sets indexed by short name + /** @brief Sets indexed by short name. */ SetNameMap sets; FormatRulesNameMap formats; - /// Loader responsible for file discovery and parsing + /** @brief Loader responsible for file discovery and parsing. */ CardDatabaseLoader *loader; - /// Current load status of the database + /** @brief Current load status of the database. */ LoadStatus loadStatus; - /// Querier for higher-level card lookups + /** @brief Querier for higher-level card lookups. */ CardDatabaseQuerier *querier; private: @@ -64,7 +64,7 @@ private: */ void refreshCachedReverseRelatedCards(); - /// Mutexes for thread safety + /** @brief Mutexes for thread safety. */ QBasicMutex *clearDatabaseMutex = new QBasicMutex(), *addCardMutex = new QBasicMutex(), *removeCardMutex = new QBasicMutex(); diff --git a/libcockatrice_card/libcockatrice/card/database/card_database_manager.h b/libcockatrice_card/libcockatrice/card/database/card_database_manager.h index 58a744fbb..c7de66a25 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database_manager.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database_manager.h @@ -67,13 +67,13 @@ private: /** @brief Private destructor. */ ~CardDatabaseManager() = default; - /// Static card preference provider pointer (default: Noop) + /** @brief Static card preference provider pointer (default: Noop). */ static ICardPreferenceProvider *cardPreferenceProvider; - /// Static path provider pointer (default: Noop) + /** @brief Static path provider pointer (default: Noop). */ static ICardDatabasePathProvider *pathProvider; - /// Static set priority controller pointer (default: Noop) + /** @brief Static set priority controller pointer (default: Noop). */ static ICardSetPriorityController *setPriorityController; }; diff --git a/libcockatrice_card/libcockatrice/card/set/card_set.h b/libcockatrice_card/libcockatrice/card/set/card_set.h index 2cedb597e..8e16e01df 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set.h @@ -107,31 +107,31 @@ public: */ [[nodiscard]] QString getCorrectedShortName() const; - /// @return Short identifier of the set. + /** @return Short identifier of the set. */ [[nodiscard]] QString getShortName() const { return shortName; } - /// @return Descriptive name of the set. + /** @return Descriptive name of the set. */ [[nodiscard]] QString getLongName() const { return longName; } - /// @return Type/category string of the set. + /** @return Type/category string of the set. */ [[nodiscard]] QString getSetType() const { return setType; } - /// @return Release date of the set. + /** @return Release date of the set. */ [[nodiscard]] QDate getReleaseDate() const { return releaseDate; } - /// @return Priority level of the set. + /** @return Priority level of the set. */ [[nodiscard]] Priority getPriority() const { return priority; @@ -190,7 +190,7 @@ public: enabled = _enabled; } - /// @return The sort key assigned to this set. + /** @return The sort key assigned to this set. */ [[nodiscard]] int getSortKey() const { return sortKey; @@ -202,7 +202,7 @@ public: */ void setSortKey(unsigned int _sortKey); - /// @return True if the set is enabled. + /** @return True if the set is enabled. */ [[nodiscard]] bool getEnabled() const { return enabled; @@ -214,7 +214,7 @@ public: */ void setEnabled(bool _enabled); - /// @return True if the set is considered known. + /** @return True if the set is considered known. */ [[nodiscard]] bool getIsKnown() const { return isknown; diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/deck_list.h b/libcockatrice_deck_list/libcockatrice/deck_list/deck_list.h index a96adeb38..e792c85dc 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/deck_list.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/deck_list.h @@ -89,7 +89,7 @@ private: mutable QString cachedDeckHash; public: - /// @name Metadata setters + /** @name Metadata setters */ ///@{ void setName(const QString &_name = QString()) { @@ -125,11 +125,11 @@ public: } ///@} - /// @brief Construct an empty deck. + /** @brief Construct an empty deck. */ explicit DeckList(); - /// @brief Construct from a serialized native-format string. + /** @brief Construct from a serialized native-format string. */ explicit DeckList(const QString &nativeString); - /// @brief Construct from components + /** @brief Construct from components. */ DeckList(const Metadata &metadata, const DecklistNodeTree &tree, const QMap &sideboardPlans = {}); @@ -144,8 +144,10 @@ public: return &tree; } - /// @name Metadata getters - /// The individual metadata getters still exist for backwards compatibility. + /** + * @name Metadata getters + * The individual metadata getters still exist for backwards compatibility. + */ ///@{ //! \todo Figure out when we can remove them. const Metadata &getMetadata() const @@ -183,7 +185,7 @@ public: return metadata.isEmpty() && getCardList().isEmpty(); } - /// @name Sideboard plans + /** @name Sideboard plans */ ///@{ QList getCurrentSideboardPlan() const; void setCurrentSideboardPlan(const QList &plan); @@ -193,7 +195,7 @@ public: } ///@} - /// @name Serialization (XML) + /** @name Serialization (XML) */ ///@{ bool readElement(QXmlStreamReader *xml); void write(QXmlStreamWriter *xml) const; @@ -204,7 +206,7 @@ public: bool saveToFile_Native(QIODevice *device) const; ///@} - /// @name Serialization (Plain text) + /** @name Serialization (Plain text) */ ///@{ bool loadFromStream_Plain(QTextStream &stream, bool preserveMetadata, @@ -216,7 +218,7 @@ public: QString writeToString_Plain(bool prefixSideboardCards = true, bool slashTappedOutSplitCards = false) const; ///@} - /// @name Deck manipulation + /** @name Deck manipulation */ ///@{ void cleanList(bool preserveMetadata = false); bool isEmpty() const @@ -238,7 +240,7 @@ public: const bool formatLegal = true); ///@} - /// @name Deck identity + /** @name Deck identity */ ///@{ QString getDeckHash() const; void refreshDeckHash(); diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/deck_list_node_tree.h b/libcockatrice_deck_list/libcockatrice/deck_list/deck_list_node_tree.h index 6de760634..8ef0b18a5 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/deck_list_node_tree.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/deck_list_node_tree.h @@ -12,11 +12,11 @@ class DecklistNodeTree InnerDecklistNode *root; ///< Root of the deck tree (zones + cards). public: - /// @brief Constructs an empty DecklistNodeTree + /** @brief Constructs an empty DecklistNodeTree. */ explicit DecklistNodeTree(); - /// @brief Copy constructor. Deep copies the tree + /** @brief Copy constructor. Deep copies the tree. */ explicit DecklistNodeTree(const DecklistNodeTree &other); - /// @brief Copy-assignment operator. Deep copies the tree + /** @brief Copy-assignment operator. Deep copies the tree. */ DecklistNodeTree &operator=(const DecklistNodeTree &other); virtual ~DecklistNodeTree(); diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/sideboard_plan.h b/libcockatrice_deck_list/libcockatrice/deck_list/sideboard_plan.h index 524217c2d..fff4ff2f3 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/sideboard_plan.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/sideboard_plan.h @@ -51,19 +51,19 @@ public: */ void write(QXmlStreamWriter *xml) const; - /// @return The plan name. + /** @return The plan name. */ [[nodiscard]] QString getName() const { return name; } - /// @return Const reference to the move list. + /** @return Const reference to the move list. */ [[nodiscard]] const QList &getMoveList() const { return moveList; } - /// @brief Replace the move list with a new one. + /** @brief Replace the move list with a new one. */ void setMoveList(const QList &_moveList); }; diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_card_node.h b/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_card_node.h index 88d8b0930..df903a168 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_card_node.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_card_node.h @@ -58,40 +58,40 @@ public: { } - /// @return The number of copies of this card in the deck. + /** @return The number of copies of this card in the deck. */ [[nodiscard]] virtual int getNumber() const = 0; - /// @param _number Set the number of copies of this card. + /** @param _number Set the number of copies of this card. */ virtual void setNumber(int _number) = 0; - /// @return The display name of this card. + /** @return The display name of this card. */ [[nodiscard]] QString getName() const override = 0; - /// @param _name Set the display name of this card. + /** @param _name Set the display name of this card. */ virtual void setName(const QString &_name) = 0; - /// @return The provider identifier for this card (e.g., UUID). + /** @return The provider identifier for this card (e.g., UUID). */ [[nodiscard]] virtual QString getCardProviderId() const override = 0; - /// @param _cardProviderId Set the provider identifier for this card. + /** @param _cardProviderId Set the provider identifier for this card. */ virtual void setCardProviderId(const QString &_cardProviderId) = 0; - /// @return The abbreviated set code (e.g., "NEO"). + /** @return The abbreviated set code (e.g., "NEO"). */ [[nodiscard]] virtual QString getCardSetShortName() const override = 0; - /// @param _cardSetShortName Set the abbreviated set code. + /** @param _cardSetShortName Set the abbreviated set code. */ virtual void setCardSetShortName(const QString &_cardSetShortName) = 0; - /// @return The collector number of the card within its set. + /** @return The collector number of the card within its set. */ [[nodiscard]] virtual QString getCardCollectorNumber() const override = 0; - /// @param _cardSetNumber Set the collector number. + /** @param _cardSetNumber Set the collector number. */ virtual void setCardCollectorNumber(const QString &_cardSetNumber) = 0; - /// @return The format legality of the card + /** @return The format legality of the card. */ virtual bool getFormatLegality() const = 0; - /// @param _formatLegal If the card is considered legal + /** @param _formatLegal If the card is considered legal. */ virtual void setFormatLegality(const bool _formatLegal) = 0; /** diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_node.h b/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_node.h index 877705705..a39f0e7b2 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_node.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/tree/abstract_deck_list_node.h @@ -101,7 +101,7 @@ public: */ explicit AbstractDecklistNode(InnerDecklistNode *_parent = nullptr, int position = -1); - /// Virtual destructor. Child classes must clean up their resources. + /** @brief Virtual destructor. Child classes must clean up their resources. */ virtual ~AbstractDecklistNode() = default; /** @@ -136,7 +136,7 @@ public: */ [[nodiscard]] virtual bool isDeckHeader() const = 0; - /// @return The parent node, or nullptr if this is the root. + /** @return The parent node, or nullptr if this is the root. */ [[nodiscard]] InnerDecklistNode *getParent() const { return parent; diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/tree/deck_list_card_node.h b/libcockatrice_deck_list/libcockatrice/deck_list/tree/deck_list_card_node.h index b3d42b89a..3bab5405a 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/tree/deck_list_card_node.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/tree/deck_list_card_node.h @@ -93,79 +93,79 @@ public: */ explicit DecklistCardNode(DecklistCardNode *other, InnerDecklistNode *_parent); - /// @return The quantity of this card. + /** @return The quantity of this card. */ [[nodiscard]] int getNumber() const override { return number; } - /// @param _number Set the quantity of this card. + /** @param _number Set the quantity of this card. */ void setNumber(int _number) override { number = _number; } - /// @return The display name of this card. + /** @return The display name of this card. */ [[nodiscard]] QString getName() const override { return name; } - /// @param _name Set the display name of this card. + /** @param _name Set the display name of this card. */ void setName(const QString &_name) override { name = _name; } - /// @return The provider identifier for this card. + /** @return The provider identifier for this card. */ [[nodiscard]] QString getCardProviderId() const override { return cardProviderId; } - /// @param _providerId Set the provider identifier for this card. + /** @param _providerId Set the provider identifier for this card. */ void setCardProviderId(const QString &_providerId) override { cardProviderId = _providerId; } - /// @return The short set code (e.g., "NEO"). + /** @return The short set code (e.g., "NEO"). */ [[nodiscard]] QString getCardSetShortName() const override { return cardSetShortName; } - /// @param _cardSetShortName Set the short set code. + /** @param _cardSetShortName Set the short set code. */ void setCardSetShortName(const QString &_cardSetShortName) override { cardSetShortName = _cardSetShortName; } - /// @return The collector number of this card within its set. + /** @return The collector number of this card within its set. */ [[nodiscard]] QString getCardCollectorNumber() const override { return cardSetNumber; } - /// @param _cardSetNumber Set the collector number. + /** @param _cardSetNumber Set the collector number. */ void setCardCollectorNumber(const QString &_cardSetNumber) override { cardSetNumber = _cardSetNumber; } - /// @return The format legality of the card + /** @return The format legality of the card. */ [[nodiscard]] bool getFormatLegality() const override { return formatLegal; } - /// @param _formatLegal If the card is considered legal + /** @param _formatLegal If the card is considered legal. */ void setFormatLegality(const bool _formatLegal) override { formatLegal = _formatLegal; } - /// @return Always false; card nodes are not deck headers. + /** @return Always false; card nodes are not deck headers. */ [[nodiscard]] bool isDeckHeader() const override { return false; diff --git a/libcockatrice_deck_list/libcockatrice/deck_list/tree/inner_deck_list_node.h b/libcockatrice_deck_list/libcockatrice/deck_list/tree/inner_deck_list_node.h index f4c48afce..81c37dffa 100644 --- a/libcockatrice_deck_list/libcockatrice/deck_list/tree/inner_deck_list_node.h +++ b/libcockatrice_deck_list/libcockatrice/deck_list/tree/inner_deck_list_node.h @@ -18,11 +18,11 @@ #include "abstract_deck_list_node.h" -/// Constant for the "main" deck zone name. +/** @brief Constant for the "main" deck zone name. */ #define DECK_ZONE_MAIN "main" -/// Constant for the "sideboard" zone name. +/** @brief Constant for the "sideboard" zone name. */ #define DECK_ZONE_SIDE "side" -/// Constant for the "tokens" zone name. +/** @brief Constant for the "tokens" zone name. */ #define DECK_ZONE_TOKENS "tokens" /** @@ -93,13 +93,13 @@ public: */ void setSortMethod(DeckSortMethod method) override; - /// @return The internal name of this node. + /** @return The internal name of this node. */ [[nodiscard]] QString getName() const override { return name; } - /// @param _name Set the internal name of this node. + /** @param _name Set the internal name of this node. */ void setName(const QString &_name) { name = _name; @@ -122,25 +122,25 @@ public: */ [[nodiscard]] virtual QString getVisibleName() const; - /// @return Always empty for container nodes. + /** @return Always empty for container nodes. */ [[nodiscard]] QString getCardProviderId() const override { return ""; } - /// @return Always empty for container nodes. + /** @return Always empty for container nodes. */ [[nodiscard]] QString getCardSetShortName() const override { return ""; } - /// @return Always empty for container nodes. + /** @return Always empty for container nodes. */ [[nodiscard]] QString getCardCollectorNumber() const override { return ""; } - /// @return Always true; InnerDecklistNode represents deck structure. + /** @return Always true; InnerDecklistNode represents deck structure. */ [[nodiscard]] bool isDeckHeader() const override { return true; @@ -196,10 +196,10 @@ public: */ bool compare(AbstractDecklistNode *other) const override; - /// @copydoc compare(AbstractDecklistNode*) const + /** @copydoc compare(AbstractDecklistNode*) const */ bool compareNumber(AbstractDecklistNode *other) const; - /// @copydoc compare(AbstractDecklistNode*) const + /** @copydoc compare(AbstractDecklistNode*) const */ bool compareName(AbstractDecklistNode *other) const; /**