Improve documentation

3 files changed, 66 insertions, 9 deletions

diff --git a/src/game_tab/left_panel/GameTabLeftPanel.hpp b/src/game_tab/left_panel/GameTabLeftPanel.hpp
index fe4176e..c012ddc 100644
--- a/src/game_tab/left_panel/GameTabLeftPanel.hpp
+++ b/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;
diff --git a/src/game_tab/left_panel/board/BoardCanvas.hpp b/src/game_tab/left_panel/board/BoardCanvas.hpp
index cd8ace9..743466a 100644
--- a/src/game_tab/left_panel/board/BoardCanvas.hpp
+++ b/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);
diff --git a/src/game_tab/left_panel/board/Theme.hpp b/src/game_tab/left_panel/board/Theme.hpp
index c3acf10..ccf4949 100644
--- a/src/game_tab/left_panel/board/Theme.hpp
+++ b/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);
 };