From fa9d534e9479b5bb8c8ae104b643815cf16e3549 Mon Sep 17 00:00:00 2001 From: "A.M. Rowsell" Date: Tue, 16 Sep 2025 03:21:53 -0400 Subject: [PATCH] docs: bringing in doxygen-awesome-css, added more inline documentation The doxygen-awesome-css project is just a nice, simple, customizable CSS system for making doxygen look less like 1992 and more like 2022. I need to spend a bunch of time tweaking it to make it look good, and perhaps match it to the style already used at chess.frzn.dev. Added more inline Doxycomments, and also generated an image that represents the logical layout of the boardGrid member variable, showing the mirrored layout. This works well for our project because of the way the serial data comes in. --- .gitignore | 6 +++--- .gitmodules | 3 +++ Doxyfile | 10 +++++----- doxygen-awesome-css | 1 + inc/Board.hpp | 28 +++++++++++++++++++++++++--- inc/Piece.hpp | 2 +- 6 files changed, 38 insertions(+), 12 deletions(-) create mode 100644 .gitmodules create mode 160000 doxygen-awesome-css diff --git a/.gitignore b/.gitignore index 3ac12ed..23f1281 100644 --- a/.gitignore +++ b/.gitignore @@ -23,8 +23,7 @@ *.debug *.yml html/ -nbproject/private/ -nbproject/Package-*.bash +nbproject/* build/ nbbuild/ dist/ @@ -42,4 +41,5 @@ chessmcu_default/ localTest/ docs/ .ca/ -*.kate-swp \ No newline at end of file +*.kate-swp +*orig \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d8da1e4 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "doxygen-awesome-css"] + path = doxygen-awesome-css + url = https://github.com/jothepro/doxygen-awesome-css.git diff --git a/Doxyfile b/Doxyfile index 85dcf26..1d995e4 100644 --- a/Doxyfile +++ b/Doxyfile @@ -540,13 +540,13 @@ EXTRACT_ALL = YES # be included in the documentation. # The default value is: NO. -EXTRACT_PRIVATE = NO +EXTRACT_PRIVATE = YES # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual # methods of a class will be included in the documentation. # The default value is: NO. -EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PRIV_VIRTUAL = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. @@ -1146,7 +1146,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = docs/images # The INPUT_FILTER tag can be used to specify a program that Doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1456,7 +1456,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doxygen-awesome-css/doxygen-awesome.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1479,7 +1479,7 @@ HTML_EXTRA_FILES = # The default value is: AUTO_LIGHT. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_COLORSTYLE = AUTO_LIGHT +HTML_COLORSTYLE = LIGHT # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the style sheet and background images according to diff --git a/doxygen-awesome-css b/doxygen-awesome-css new file mode 160000 index 0000000..568f56c --- /dev/null +++ b/doxygen-awesome-css @@ -0,0 +1 @@ +Subproject commit 568f56cde6ac78b6dfcc14acd380b2e745c301ea diff --git a/inc/Board.hpp b/inc/Board.hpp index 6bf34b7..4d0677c 100644 --- a/inc/Board.hpp +++ b/inc/Board.hpp @@ -6,6 +6,14 @@ // This Source Code Form is "Incompatible With Secondary Licenses", as // defined by the Mozilla Public License, v. 2.0. +/** @file Board.hpp + * @brief The header file for the Board class + * + * This contains the class definition for the logical representation of the chessboard + * itself, as well as a few ancillary enums and forward declarations to make the code + * easier to read (hopefully). Unlike the Piece.hpp header, there's no inheritance + * or virtual functions so this "half" of the code is a bit simpler to follow. + */ #ifndef BOARD_HPP #define BOARD_HPP @@ -14,16 +22,29 @@ #include #include #include "Piece.hpp" -// suggested to forward declare here, and put include in the .cpp class Piece; +/** @enum Players + * @brief An enum for the white and black players + */ enum Players { PL_WHITE, PL_BLACK }; struct Square; +/** @class Board Board.hpp inc/Board.hpp + * @brief This class abstracts the chess board itself + * + * The heart of the entire code is contained in the member variable boardGrid, which + * is a representation of the board. It's a 2D vector of Pieces, which are stored using + * smart pointers. When other functions want to view the board, they do so with the included + * getPieceAt() getters, which return raw pointers so ownership isn't transferred. + * + * Outside functions/methods can also change the state of the board with setPieceAt() which + * can allow one to move a piece (empty squares being nullptr) or add pieces to the Board when + * required. + */ class Board { private: - friend class Piece; // this doesn't seem to do anything - std::vector>> boardGrid; + std::vector>> 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" */ Players playerTurn; // let's get super object-oriented, baby // these help the getters and setters access the boardGrid @@ -48,6 +69,7 @@ class Board { virtual ~Board(); // These are to allow Piece to access Board in a controlled way + // instead of adding a friend declaration for every subclass // ----- Getters ----- Piece* getPieceAt(int r, int f) { return at(r, f).get(); diff --git a/inc/Piece.hpp b/inc/Piece.hpp index f7607ea..76a9c18 100644 --- a/inc/Piece.hpp +++ b/inc/Piece.hpp @@ -75,7 +75,7 @@ struct Move { }; /** - * @class Piece Piece.hpp "inc/Piece.hpp" + * @class Piece Piece.hpp inc/Piece.hpp * @brief A class abstracting chess pieces * * This is a polymorphic base class containing the basic properties all chess pieces have.