docs: Documented more of the Board class

inc/Board.hpp

@@ -44,7 +44,9 @@ struct Square;
  */
 class Board {
   private:
-    std::vector<std::vector<std::unique_ptr<Piece>>> boardGrid; /**< This holds the game state. It is a 2D vector of Piece types, or nullptr for empty squares @image html boardGrid.png "Logical diagram of boardGrid vector" */
+    std::vector<std::vector<std::unique_ptr<Piece>>> boardGrid; /**< This holds the game state. 
+                                                                 * It is a 2D vector of Piece types, or nullptr for empty squares 
+                                                                 * @image html boardGrid.svg "Logical diagram of boardGrid vector" */
     Players playerTurn;
     // let's get super object-oriented, baby
     // these help the getters and setters access the boardGrid
@@ -108,15 +110,59 @@ class Board {
         return at(sq) == nullptr;
     }
 
+    /** A function to setup the initial board
+     * 
+     * This initializes the boardGrid with the black and white pieces
+     * in their normal starting positions. All empty squares are set
+     * to nullptr.
+     */
     void setupInitialPosition();
-
+    /** This function sets the entire board to nullptr
+     * 
+     * This should, if I understand correctly, destroy
+     * all the Piece instances that existed because they will no longer
+     * have any owners, and smart pointers should auto destruct.
+     */
     void clearBoard();
+    /** This does the actual moving of a piece from one square to another
+     * 
+     * Beware! This function does \e not validate if the move is legal. It
+     * will simply do whatever it is told to do. So only call this once you
+     * are positive the move is legal.
+     * Moves to an empty square are simple, just move the Piece to that other
+     * square. Captures have to also take note of the piece type captured
+     * and add it to the total captured by that side. This should also destroy
+     * the smart pointer automatically.
+     * @param from The originating square for the Piece that is moving
+     * @param to And of course, where it will end up
+     */
     void movePiece(Square from, Square to);
     void nextTurn();
+    /** This function takes a standard FEN string and sets up the board.
+     * 
+     * FEN is a standard notation that describes only an exact position and
+     * other important things like whose turn it is, whether sides can castle,
+     * but it does \e not include the move history of the game. This makes it
+     * a simpler format for sharing particular interesting positions.
+     * 
+     * @param strFEN A std::string that contains a valid FEN position
+     * @return 0 on success, -1 if the FEN string is invalid
+     */
     int setupFromFEN(std::string strFEN);
     bool isInBounds(Square square) const;
     // serial shift register stuff
     uint64_t serialBoard = 0xFFFF00000000FFFF; // opening position
+    /** This takes an incoming serial stream and detects if anything has moved.
+     * 
+     * The input is one bit per piece, so it can only detect the presence or
+     * absence of pieces on any particular square. This is the crux of our design,
+     * using simpler reed switches for detection instead of RFID or any other two-way
+     * communication with the pieces. This moves a lot of the complexity into software,
+     * though a lot of the complexity is actually quite easy to deal with from a software
+     * point of view.
+     * 
+     * @param incomingBoard A 64-bit value, representing 1 bit per piece.
+     */
     void deserializeBoard(uint64_t incomingBoard);
 };