Standardize Doxygen documentation (#6885)

cockatrice/src/game/player/card_menu_action_type.h

@@ -1,8 +1,8 @@
 /**
  * @file card_menu_action_type.h
  * @ingroup GameMenusPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_CARD_MENU_ACTION_TYPE_H
 #define COCKATRICE_CARD_MENU_ACTION_TYPE_H

cockatrice/src/game/player/event_processing_options.h

@@ -1,8 +1,8 @@
 /**
  * @file event_processing_options.h
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_EVENT_PROCESSING_OPTIONS_H
 #define COCKATRICE_EVENT_PROCESSING_OPTIONS_H

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;
 };
 

cockatrice/src/game/player/menu/card_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file card_menu.h
  * @ingroup GameMenusCards
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_CARD_MENU_H
 #define COCKATRICE_CARD_MENU_H

cockatrice/src/game/player/menu/custom_zone_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file custom_zone_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_CUSTOM_ZONE_MENU_H
 #define COCKATRICE_CUSTOM_ZONE_MENU_H

cockatrice/src/game/player/menu/grave_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file grave_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_GRAVE_MENU_H
 #define COCKATRICE_GRAVE_MENU_H

cockatrice/src/game/player/menu/hand_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file hand_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_HAND_MENU_H
 #define COCKATRICE_HAND_MENU_H

cockatrice/src/game/player/menu/library_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file library_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_LIBRARY_MENU_H
 #define COCKATRICE_LIBRARY_MENU_H

cockatrice/src/game/player/menu/move_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file move_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_MOVE_MENU_H
 #define COCKATRICE_MOVE_MENU_H

cockatrice/src/game/player/menu/player_menu.h

@@ -41,7 +41,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);
@@ -71,9 +71,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:
@@ -89,11 +89,13 @@ 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<AbstractPlayerComponent *> 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 <typename MenuT, typename... Args> MenuT *addManagedMenu(Args &&...args)
     {
         auto *menu = new MenuT(std::forward<Args>(args)...);
@@ -102,7 +104,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 <typename ComponentT, typename... Args> ComponentT *createManagedComponent(Args &&...args)
     {
         auto *component = new ComponentT(std::forward<Args>(args)...);

cockatrice/src/game/player/menu/pt_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file pt_menu.h
  * @ingroup GameMenusCards
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PT_MENU_H
 #define COCKATRICE_PT_MENU_H

cockatrice/src/game/player/menu/rfg_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file rfg_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_RFG_MENU_H
 #define COCKATRICE_RFG_MENU_H

cockatrice/src/game/player/menu/say_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file say_menu.h
  * @ingroup GameMenusPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_SAY_MENU_H
 #define COCKATRICE_SAY_MENU_H

cockatrice/src/game/player/menu/sideboard_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file sideboard_menu.h
  * @ingroup GameMenusZones
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_SIDEBOARD_MENU_H
 #define COCKATRICE_SIDEBOARD_MENU_H

cockatrice/src/game/player/menu/utility_menu.h

@@ -1,8 +1,8 @@
 /**
  * @file utility_menu.h
  * @ingroup GameMenusPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_UTILITY_MENU_H
 #define COCKATRICE_UTILITY_MENU_H

cockatrice/src/game/player/player_actions.h

@@ -2,8 +2,8 @@
  * @file player_actions.h
  *  @ingroup GameLogicActions
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_ACTIONS_H
 #define COCKATRICE_PLAYER_ACTIONS_H

cockatrice/src/game/player/player_area.h

@@ -1,8 +1,8 @@
 /**
  * @file player_area.h
  * @ingroup GameGraphicsPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_AREA_H
 #define COCKATRICE_PLAYER_AREA_H

cockatrice/src/game/player/player_event_handler.h

@@ -1,8 +1,8 @@
 /**
  * @file player_event_handler.h
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_EVENT_HANDLER_H
 #define COCKATRICE_PLAYER_EVENT_HANDLER_H

cockatrice/src/game/player/player_graphics_item.h

@@ -1,8 +1,8 @@
 /**
  * @file player_graphics_item.h
  * @ingroup GameGraphicsPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_GRAPHICS_ITEM_H
 #define COCKATRICE_PLAYER_GRAPHICS_ITEM_H

cockatrice/src/game/player/player_info.h

@@ -1,8 +1,8 @@
 /**
  * @file player_info.h
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_INFO_H
 #define COCKATRICE_PLAYER_INFO_H

cockatrice/src/game/player/player_list_widget.h

@@ -1,8 +1,8 @@
 /**
  * @file player_list_widget.h
  * @ingroup GameWidgets
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef PLAYERLISTWIDGET_H
 #define PLAYERLISTWIDGET_H

cockatrice/src/game/player/player_logic.h

@@ -1,8 +1,8 @@
 /**
  * @file player.h
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef PLAYER_H
 #define PLAYER_H

cockatrice/src/game/player/player_manager.h

@@ -1,8 +1,8 @@
 /**
  * @file player_manager.h
  * @ingroup GameLogicPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef COCKATRICE_PLAYER_MANAGER_H
 #define COCKATRICE_PLAYER_MANAGER_H

cockatrice/src/game/player/player_target.h

@@ -1,8 +1,8 @@
 /**
  * @file player_target.h
  * @ingroup GameGraphicsPlayers
- * @brief TODO: Document this.
  */
+//! \todo Document this file.
 
 #ifndef PLAYERTARGET_H
 #define PLAYERTARGET_H