Improve documentation

src/MainWindow.hpp

@@ -15,9 +15,16 @@ wxDECLARE_EVENT(CLOSE_TAB_EVENT, wxCommandEvent);
 wxDECLARE_EVENT(REFRESH_ENGINE_LIST, wxCommandEvent);
 wxDECLARE_EVENT(CLOSE_LINKED_TAB, wxCommandEvent);
 
+/**
+ * @brief Main GUI window of OChess
+ * 
+ */
 class MainWindow : public MainFrame {
+  /// @brief Preference popup window
   wxPreferencesEditor *prefsEditor;
+  /// @brief Menu to manage existing chess engines
   wxMenu *manageMenu;
+  /// @brief Store the number of available chess engines (to create entries in the menus)
   int engine_count;
 
   void OnClose(wxCloseEvent &e);

src/base_tab/BaseGameTab.hpp

@@ -5,6 +5,10 @@
 #include "gamebase/PGNGameBase.hpp"
 #include "GameListManager.hpp"
 
+/**
+ * @brief A BaseTab sub-tab to list and search games
+ * 
+ */
 class BaseGameTab : public TabBase_TabGames {
   std::shared_ptr<GameBase> base;
 

src/base_tab/BaseImportTab.hpp

@@ -6,6 +6,10 @@
 #include <vector>
 #include <utility>
 
+/**
+ * @brief A BaseTab sub-tab to import games
+ * 
+ */
 class BaseImportTab : public TabBase_TabImport {
   TabInfos *main_tab;
   std::shared_ptr<GameListManager> glm;

src/base_tab/BaseManageTab.hpp

@@ -6,6 +6,10 @@
 #include "BaseImportTab.hpp"
 #include "BaseGameTab.hpp"
 
+/**
+ * @brief A BaseTab sub-tab to manage games
+ * 
+ */
 class BaseManageTab : public TabBase_TabManage {
 
     /// Never free the following pointers in that class

src/base_tab/BaseTab.hpp

@@ -13,6 +13,10 @@ wxDECLARE_EVENT(CLOSE_LINKED_TAB, wxCommandEvent);
 // Local events
 wxDECLARE_EVENT(REFRESH_MANAGE_TAB, wxCommandEvent);
 
+/**
+ * @brief Class that represents an opened chess games database in the MainWindow
+ * 
+ */
 class BaseTab : public TabBase, public TabInfos {
   /// @brief The opened database
   std::shared_ptr<GameBase> base;

src/base_tab/GameListManager.hpp

@@ -25,7 +25,7 @@ typedef struct Item {
 } RType;
 
 /**
- * @brief A manager for wxListCtrl that display games
+ * @brief A helper class to manage a wxListCtrl that display games
  * 
  */
 class GameListManager {

src/base_tab/gamebase/GameBase.hpp

@@ -3,6 +3,10 @@
 #include <algorithm>
 #include <vector>
 
+/**
+ * @brief Represent the interface that each database type (such as PGNGameBase) must follow
+ * to be accessible in OChess.
+ */
 class GameBase {
 
 public:

src/base_tab/gamebase/PGNGameBase.hpp

@@ -3,6 +3,10 @@
 #include "GameBase.hpp"
 #include "pgnp.hpp"
 
+/**
+ * @brief Used to open PGN files
+ * 
+ */
 class PGNGameBase : public GameBase {
   pgnp::PGN *pgn;
   bool hasNextGame;

src/binres/binres.hpp

@@ -1,7 +1,32 @@
+/**
+ * @file binres.hpp
+ * @author Manzerbredes
+ * @brief Binary resources functions
+ * @version 0.1
+ * @date 2023-05-12
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ */
 #pragma once
 
 #include "ochess.hpp"
 
+/**
+ * @brief Load an icon from embedded binary resources and rescale it
+ * to a specified @a size
+ *
+ * @param icon The icon name
+ * @param size Scale the icon to the specified size
+ * @return wxBitmap 
+ */
 wxBitmap LoadPNG(std::string icon, wxSize size);
+
+/**
+ * @brief Load an icon from embedded binary resources
+ * 
+ * @param icon 
+ * @return wxBitmap 
+ */
 wxBitmap LoadPNG(std::string icon);
 

src/config.h.in

@@ -1,3 +1,13 @@
+/**
+ * @file config.h.in
+ * @author Manzerbredes
+ * @brief CMake configuration entries
+ * @version 0.1
+ * @date 2023-05-12
+ * 
+ * @copyright Copyright (c) 2023
+ * 
+ */
 #define OCHESS_VERSION "@PROJECT_VERSION@"
 #define OCHESS_MAJOR "@PROJECT_VERSION_MAJOR@"
 #define OCHESS_MINOR "@PROJECT_VERSION_MINOR@"

src/engine_tab/EngineTab.hpp

@@ -6,6 +6,10 @@ wxDECLARE_EVENT(CLOSE_TAB_EVENT, wxCommandEvent);
 wxDECLARE_EVENT(REFRESH_ENGINE_LIST, wxCommandEvent);
 wxDECLARE_EVENT(REFRESH_TAB_TITLE, wxCommandEvent);
 
+/**
+ * @brief Tab used to configure UCI chess engines
+ * 
+ */
 class EngineTab : public TabEngine, public TabInfos {
   std::string confGroup, enginePath;
   uciadapter::UCI *engine;

src/game_tab/GameTab.hpp

@@ -15,6 +15,10 @@ wxDECLARE_EVENT(REFRESH_TAB_TITLE, wxCommandEvent);
 wxDECLARE_EVENT(GAME_CHANGE, wxCommandEvent);
 wxDECLARE_EVENT(SHOW_ENGINE_EVALUATION, wxCommandEvent);
 
+/**
+ * @brief Main tab for opened games. Contains GameTabLeftPanel and GameTabRightPanel.
+ * 
+ */
 class GameTab : public wxPanel, public TabInfos {
   GameTabRightPanel *editor_panel;
   GameTabLeftPanel *board_panel;

src/game_tab/HalfMove.hpp

@@ -18,6 +18,7 @@ class HalfMove : public CMI::HalfMove {
   std::string src,dst;
   /// @brief Opening reach by that move while taking into account all the parents
   std::string opening, eco;
+  /// @brief Arbiter used to ensure that chess rules are followed
   chessarbiter::ChessArbiter arbiter;
 
 public:

src/game_tab/left_panel/GameTabLeftPanel.hpp

@@ -9,6 +9,10 @@
 // Foreign events
 wxDECLARE_EVENT(GAME_CHANGE, wxCommandEvent);
 
+/**
+ * @brief Panel that contains the BoardCanvas and the bottom control buttons
+ * 
+ */
 class GameTabLeftPanel : public TabGameLeftPanel {
   std::shared_ptr<Game> game;
   BoardCanvas *board_canvas;

src/game_tab/left_panel/board/BoardCanvas.hpp

@@ -40,7 +40,9 @@ wxDECLARE_EVENT(PLAY_MOVE_EVENT, wxCommandEvent);
 
 typedef std::tuple<short, short, short> ClockTime;
 
-// Drawing buffer (ANIMATIONS)
+/**
+ * @brief Drawing buffer and state for animations
+ */
 typedef struct AnimState {
   /// @brief Temporary buffer to reduce latency
   wxBitmap *buffer;
@@ -62,21 +64,39 @@ typedef struct AnimState {
   wxPoint transVect;
 } AnimState;
 
+/**
+ * @brief Current game state displayed by BoardCanvas
+ */
 typedef struct GameState {
+  /// @brief State of an arrow
   typedef struct Arrow {
     std::string src,dst;
     wxColour color=wxNullColour;
     float scale=1;
   } Arrow;
+  /// @brief State of an highlighted square
   typedef struct Square {
     std::string square;
     wxColour color=wxNullColour;
   } Square;
   std::string white, black;
+  /**
+   * @brief Contains all the board squares with their pieces in the same order as the FEN specification. 
+   * 
+   * For example, the following board
+   @verbatim
+   "rnb                                                          RNB"
+   @endverbatim
+   * contains a black rook on a8, a black knight on b8, a black bishop on c8, a white rook
+   * on a1, a white knight on b1 and a white bishop on c1
+   */
   std::string board;
+  /// @brief When there is a pending promotion, this variable contains the coordinate of the square on which the promotion takes place.
   std::string promotion;
   std::map<char, std::uint8_t> captures;
+  /// @brief Square to highlight (combined to BoardCanvas::squares_hl)
   std::vector<Square> squares_hl;
+  /// @brief Arrow to draw (combined to BoardCanvas::arrows)
   std::vector<Arrow> arrows;
   bool is_black_turn;
   bool mat_black;
@@ -86,29 +106,44 @@ typedef struct GameState {
   ClockTime black_time={-1,-1,-1}, white_time={-1,-1,-1};
 } GameState;
 
+/**
+ * @brief This class draws the chess board (squares, pieces, arrows and every other board related components).
+ * 
+ */
 class BoardCanvas : public wxPanel {
-  // *t is theme for board+pieces and
-  // *t_captures is theme for captured pieces (scale down version of t)
-  Theme *t, *t_captures;
+  /// @brief Contains the theme for squares and pieces (see Theme)
+  Theme *t;
+  /// @brief Scale down version of BoardCanvas::t for the captured pieces by black and white
+  Theme *t_captures;
+  /// @brief Stores the color of the arrows
   wxColour color_arrows;
+  /// @brief Offset used for the start point of the arrows (this way, arrows do not completely overlap on the pieces)
   int arrows_offset;
+  /// @brief Thickness of the arrows
   std::uint8_t arrow_thickness;
+  /// @brief Player names
   std::string white_player,black_player;
-  // Current highlighted squares and arrows:
+  /// @brief Current highlighted squares that were highlighted with the mouse
   std::vector<GameState::Square> squares_hl;
+  /// @brief Current drawn arrows that were drawn with the mouse
   std::vector<GameState::Arrow> arrows;
 
   // Various canvas state variables
   bool black_side, is_dragging, valid_drag, arrow_drag, is_black_turn;
   std::int32_t boardX, boardY, square_width, piece_width, mouseX, mouseY, lastClickX,
       lastClickY;
+  /// @brief Contains an up to date dimension of the canvas size and its use in various places
   wxSize canvas_size;
+  /// @brief Used for drag and drop
   wxPoint active_square;
   std::map<char, std::uint8_t> captures;
-  bool frozen,lock_square_size;
+  /// @brief Board can be frozen (to preview the board themes in the preference menu for example)
+  bool frozen;
+  bool lock_square_size;
 
-  // Current animation state
+  /// @brief Current animation state
   AnimState adata;
+  /// @brief Current board state (contains all the game state)
   GameState gs;
 
   /// @brief Draw an arrow from a source point to a destination point on DC
@@ -121,9 +156,11 @@ public:
   BoardCanvas(wxFrame *parent,std::uint32_t square_width, bool frozen);
   ~BoardCanvas();
   void ApplyPreferences();
-  /// @brief Draw current state of the board (GameState) on the given wxDC
+  /// @brief Draw current board state BoardCanvas::gs on the given @a wxDC
   void DrawBoard(wxDC &dc);
+  /// @brief Callback called by wxWidgets to refresh the canvas
   void OnPaint(wxPaintEvent &event);
+  /// @brief Callback called by wxWidgets to handle mouse events
   void MouseEvent(wxMouseEvent &event);
   /// @brief Zomm in/out on the canvas
   void Zoom(std::int32_t zoom);

src/game_tab/left_panel/board/Theme.hpp

@@ -12,6 +12,10 @@
 #define DEFAULT_PIECE_THEME "assets/pieces/cburnett.png"
 #define DEFAULT_SQUARE_THEME "assets/boards/chesscom_8bits.png"
 
+/**
+ * @brief The in memory board theme (used by BoardCanvas)
+ * 
+ */
 class Theme {
 private:
   std::unordered_map<char, wxImage> skin;
@@ -21,18 +25,30 @@ private:
 
 public:
   Theme();
+  /// @brief Create piece using two png file path
   Theme(std::string piece, std::string square);
   ~Theme();
+  /// @brief Load piece skin image (break image tile into individual pieces)
   void LoadPiecesSkin(wxImage skin);
+  /// @brief Load square skin image (break the 2 square tiles into individual squares)
   void LoadSquaresSkin(wxImage iskin);
+  /// @brief Set pieces width
   void ResizePieces(std::uint32_t width);
+  /// @brief Set squares width
   void ResizeSquares(std::uint32_t width);
+  /// @brief Set square width and adjust piece size accordingly
   void ResizeSquaresAndPieces(std::uint32_t width);
+  /// @brief Having rounded corners on squares
   void SetSquareRadius(std::uint8_t radius);
   std::uint8_t GetSquareRadius();
   bool Zoom(int amount);
   double GetPiecesSizes();
   double GetSquaresSizes();
-
+  /**
+   * @brief Get bitmap of an element
+   * 
+   * @param c For black pieces rnbkqp for white pieces RNBKQP and # for mate symbol and s for black square and S for white square
+   * @return wxBitmap* 
+   */
   wxBitmap *Get(char c);
 };

src/game_tab/right_panel/GameTabRightPanel.hpp

@@ -12,6 +12,10 @@ wxDECLARE_EVENT(GAME_CHANGE, wxCommandEvent);
 wxDECLARE_EVENT(SHOW_ENGINE_EVALUATION, wxCommandEvent);
 wxDECLARE_EVENT(LIVE_ANALYSIS_STATUS, wxCommandEvent);
 
+/**
+ * @brief Right panel of the GameTab and contains the EditorCanvas and the live engine tab
+ * 
+ */
 class GameTabRightPanel : public TabGameRightPanel {
   std::shared_ptr<Game> game;
   EditorCanvas *editor_canvas;

src/game_tab/right_panel/LiveEngineDialog.hpp

@@ -7,11 +7,16 @@
 
 wxDECLARE_EVENT(SHOW_ENGINE_EVALUATION, wxCommandEvent);
 
+/// @brief Contains the current engine evaluation (sorted vector of best lines + position score in cp)
 typedef struct EngineEvaluation {
   std::vector<std::string> best_lines;
   float eval=0;
 } EngineEvaluation;
 
+/**
+ * @brief Dialog to control the current running engine on the game tab
+ * 
+ */
 class LiveEngineDialog : public DialogLiveEngine {
   uciadapter::UCI *engine;
   std::string engine_name;

src/game_tab/right_panel/editor/EditorCanvas.hpp

@@ -9,6 +9,10 @@
 // Foreign events
 wxDECLARE_EVENT(GAME_CHANGE, wxCommandEvent);
 
+/**
+ * @brief Contains the moves editor for the currently opened game
+ * 
+ */
 class EditorCanvas : public wxPanel, public cgeditor::CGEditor {
   wxPaintDC *dc;
   wxPoint Middle(cgeditor::Element e);

src/ochess.hpp

@@ -41,7 +41,7 @@
 class Game;
 class GameBase;
 /**
- * @brief Used by each tab of the GUI to attach informations additional informations and features
+ * @brief Used by each tab of the GUI to attach additional informations and features
  *
  */
 class TabInfos {

src/preferences/BoardPrefs.hpp

@@ -7,6 +7,10 @@
 #include <wx/spinctrl.h>
 #include <wx/stdpaths.h>
 
+/**
+ * @brief Configuration page for the BoardCanvas
+ * 
+ */
 class BoardPrefsPanel : public PrefsBoard {
   BoardCanvas *real_board_canvas;
   wxFileName pieces_path;
@@ -101,6 +105,10 @@ public:
   }
 };
 
+/**
+ * @brief Interface for wxWidgets to load BoardPrefsPanel into the preference window
+ * 
+ */
 class BoardPrefs : public wxPreferencesPage {
 public:
   virtual wxString GetName() const { return "Board"; }

src/preferences/EditorPrefs.hpp

@@ -6,6 +6,10 @@
 #include <wx/spinctrl.h>
 #include <wx/stdpaths.h>
 
+/**
+ * @brief Configuration page for the EditorCanvas
+ * 
+ */
 class EditorPrefsPanel : public PrefsEditor {
 
 public:
@@ -49,6 +53,10 @@ public:
   }
 };
 
+/**
+ * @brief Interface for wxWidgets to load EditorPrefsPanel into the preference window
+ * 
+ */
 class EditorPrefs : public wxPreferencesPage {
 public:
   virtual wxString GetName() const { return "Editor"; }

tools/doxygen/Doxyfile

@@ -964,6 +964,7 @@ FILE_PATTERNS          = *.c \
                          *.c++ \
                          *.java \
                          *.ii \
+                         *.in \
                          *.ixx \
                          *.ipp \
                          *.i++ \