From 22f963335e7a993a74971c1c4fcf3b2b39ea37e2 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Thu, 30 Apr 2026 07:14:17 +0000 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`52-?= =?UTF-8?q?unneeded-parameters-in-function`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docstrings generation was requested by @winapiadmin. * https://github.com/winapiadmin/chesslib/pull/55#issuecomment-4350397708 The following files were modified: * `moves_io.cpp` * `position.h` * `tests.cpp` * `types.h` --- moves_io.cpp | 23 +++++++++- position.h | 10 ++++- tests.cpp | 17 +++++++- types.h | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 166 insertions(+), 5 deletions(-) diff --git a/moves_io.cpp b/moves_io.cpp index 339bf8b..26dfebe 100644 --- a/moves_io.cpp +++ b/moves_io.cpp @@ -157,7 +157,28 @@ template Move uciToMove(const _Position &pos, std #endif return move; } -template Move parseSan(const _Position &pos, std::string_view raw_san, bool remove_illegals) { +template /** + * @brief Parses a SAN string and resolves it to a legal move for the given position. + * + * Parses standard algebraic notation (including castling forms, captures, promotions, + * disambiguation by file/rank/source square, and optional trailing check/mate markers) + * and returns the corresponding legal Move for the position. When enabled via + * `remove_illegals`, the function will iteratively trim trailing characters and retry + * parsing to attempt recovery from malformed inputs. + * + * @param pos The position against which SAN is parsed and validated. + * @param raw_san The SAN string to parse (e.g. "Nbd2", "e8=Q", "O-O"). + * @param remove_illegals If true, attempt progressive trimming of the SAN on failure + * and accept the first parsable legal move. + * @return Move The matching legal move for the SAN, or `Move::none()`/`Move::null()` + * when no move could be produced (in builds/configurations where exceptions + * are disabled). + * + * @throws IllegalMoveException If the SAN is malformed or does not correspond to any + * legal move for the position. + * @throws AmbiguousMoveException If the SAN matches more than one legal move. + */ +Move parseSan(const _Position &pos, std::string_view raw_san, bool remove_illegals) { auto do_parse = [&](std::string_view input_san) -> Move { if (input_san.empty()) return Move::none(); diff --git a/position.h b/position.h index d7a3f95..ac7fa23 100644 --- a/position.h +++ b/position.h @@ -25,7 +25,15 @@ #include #include #include -namespace chess { +/** + * Compute origin squares of pieces of a given color that attack a target square using the supplied occupancy. + * + * @param color Attacking color. + * @param square Target square being attacked. + * @param occupied Bitboard representing board occupancy used for sliding-attack calculations; the result is intersected with this occupancy. + * @return Bitboard with squares of pieces of `color` that attack `square`, masked by `occupied`. + */ + namespace chess { template struct alignas(64) HistoryEntry { // Bitboards for each piece type (white and black) diff --git a/tests.cpp b/tests.cpp index 8b54947..1c2d1e7 100644 --- a/tests.cpp +++ b/tests.cpp @@ -198,7 +198,22 @@ template struct TestEntry { InputT input; CheckInfo info; }; -template uint64_t perft(_Position &pos, int depth) { +template /** + * @brief Count leaf nodes in the move tree from a given position to a specified depth. + * + * Performs a full recursive enumeration of legal moves using the MoveGenType template parameter and + * returns the total number of leaf positions reachable exactly `depth` plies from `pos`. + * + * The function mutates `pos` while exploring moves but always restores it to its original state before returning. + * + * @tparam T Position representation type. + * @tparam mt Move generation type controlling which moves are generated. + * @tparam EnableDiv When true, prints per-move node counts and the total to stdout. + * @param pos Position to enumerate from; will be restored to its initial state on return. + * @param depth Number of plies to explore; 0 yields 1 (the current position), 1 yields the number of legal moves. + * @return uint64_t Number of leaf nodes reachable at the given depth. + */ +uint64_t perft(_Position &pos, int depth) { if (depth == 0) { return 1; } else if (depth == 1) { diff --git a/types.h b/types.h index f88af18..2cb9e09 100644 --- a/types.h +++ b/types.h @@ -190,7 +190,29 @@ constexpr Square operator+(Square s, Direction d) { return Square(int(s) + int(d constexpr Square operator-(Square s, Direction d) { return Square(int(s) - int(d)); } constexpr Square &operator+=(Square &s, Direction d) { return s = s + d; } constexpr Square &operator-=(Square &s, Direction d) { return s = s - d; } -// specifically for Polyglot (a.k.a zobrist hashing but use proper hash) +/** + * Compact 16-bit representation of a chess move. + * + * Encodes origin, destination, optional promotion piece, and special-move flags + * (promotion, en passant, castling) in a single 16-bit value and provides + * constructors, factories, and accessors for working with that packed form. + * + * Bit layout: + * - bits 0-5 : destination square (0..63) + * - bits 6-11 : origin square (0..63) + * - bits 12-13 : promotion piece type offset (KNIGHT..QUEEN) + * - bits 14-15 : special move flag (NORMAL, PROMOTION, EN_PASSANT, CASTLING) + * + * Special sentinel moves: + * - Move::none() and Move::null() are reserved sentinel values and are not + * considered valid moves by is_ok(). + * + * Usage notes: + * - Use Move::make(...) to construct moves with an explicit MoveType or a + * promotion piece type. + * - Access origin and destination with from()/to() (or from_sq()/to_sq()). + * - promotion_type() returns the promoted PieceType when the move is a promotion. + */ enum class PolyglotPiece : uint8_t { WPAWN = 1, WKNIGHT = 3, @@ -207,7 +229,92 @@ enum class PolyglotPiece : uint8_t { NO_PIECE = 12, PIECE_NB = 12 }; -// Normal board, you can use ANY! (but comfortable for certain chess engines such as Stockfish) +/** + * Map a PolyglotPiece encoding to its PieceType. + * @param p PolyglotPiece value to convert. + * @returns `NO_PIECE_TYPE` if `p` is `NO_PIECE`, otherwise the corresponding `PieceType`. + */ +/** + * Map an EnginePiece encoding to its PieceType. + * @param p EnginePiece value to convert. + * @returns `NO_PIECE_TYPE` if `p` is `NO_PIECE`, otherwise the corresponding `PieceType`. + */ +/** + * Map a ContiguousMappingPiece encoding to its PieceType. + * @param p ContiguousMappingPiece value to convert. + * @returns `NO_PIECE_TYPE` if `p` is `NO_PIECE`, otherwise the corresponding `PieceType`. + */ +/** + * Determine piece color from a PolyglotPiece encoding. + * @param pt PolyglotPiece value. + * @returns The `Color` (WHITE or BLACK) of `pt`. + */ +/** + * Determine piece color from an EnginePiece encoding. + * @param pt EnginePiece value. + * @returns The `Color` (WHITE or BLACK) of `pt`. + */ +/** + * Determine piece color from a ContiguousMappingPiece encoding. + * @param pt ContiguousMappingPiece value. + * @returns The `Color` (WHITE or BLACK) of `pt`. + */ +/** + * Construct an EnginePiece value from a PieceType and Color. + * @tparam T Must be `EnginePiece`. + * @param pt PieceType to encode. + * @param c Color of the piece. + * @returns EnginePiece encoding representing `pt` with color `c`. + */ +/** + * Construct a PolyglotPiece value from a PieceType and Color. + * @tparam T Must be `PolyglotPiece`. + * @param pt PieceType to encode. + * @param c Color of the piece. + * @returns PolyglotPiece encoding representing `pt` with color `c`. + */ +/** + * Construct a ContiguousMappingPiece value from a PieceType and Color. + * @tparam T Must be `ContiguousMappingPiece`. + * @param pt PieceType to encode. + * @param c Color of the piece. + * @returns ContiguousMappingPiece encoding representing `pt` with color `c`. + */ +/** + * Obtain the PieceType corresponding to a piece-encoding enum. + * @tparam T A piece-encoding enum type for which `is_piece_enum::value` is true. + * @param p Piece-encoding enum value. + * @returns The corresponding `PieceType`. + */ +/** + * Mask castling rights to a single color. + * @param c Color whose castling rights to select. + * @param cr Castling rights mask to filter. + * @returns Only the bits of `cr` relevant to color `c`. + */ +/** + * Bitwise OR-assign for CastlingRights. + * @param a Left-hand side castling rights (updated in-place). + * @param b Right-hand side castling rights to OR. + * @returns Reference to `a` after OR assignment. + */ +/** + * Bitwise OR for CastlingRights. + * @param a First castling-rights operand. + * @param b Second castling-rights operand. + * @returns The bitwise OR of `a` and `b`. + */ +/** + * Bitwise AND-assign for CastlingRights. + * @param a Left-hand side castling rights (updated in-place). + * @param b Right-hand side castling rights to AND. + * @returns Reference to `a` after AND assignment. + */ +/** + * Bitwise complement restricted to castling-related bits. + * @param a CastlingRights value to invert. + * @returns The complement of `a` with respect to `ANY_CASTLING` (flips only castling bits). + */ enum class EnginePiece : uint8_t { NO_PIECE, WPAWN = PAWN + 0, @@ -224,6 +331,16 @@ enum class EnginePiece : uint8_t { BKING, PIECE_NB = 16 }; +/** + * Combine two castling-rights flags and store the result in the left-hand operand. + * + * Performs a bitwise OR of `a` and `b`, updates `a` with the combined castling flags, + * and returns a reference to the modified `a`. + * + * @param a Left-hand operand to be updated with the combined castling rights. + * @param b Right-hand operand whose flags are OR-ed into `a`. + * @returns Reference to `a` after it has been updated with the combined flags. + */ enum class ContiguousMappingPiece : uint8_t { WPAWN = 0, WKNIGHT = 1, From aa9f98b720569e76673d9aef15236969948efa20 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 30 Apr 2026 07:14:43 +0000 Subject: [PATCH 2/2] Apply clang-format --- moves_io.cpp | 40 ++++++++++++++++++++-------------------- position.h | 17 +++++++++-------- tests.cpp | 37 +++++++++++++++++++++---------------- 3 files changed, 50 insertions(+), 44 deletions(-) diff --git a/moves_io.cpp b/moves_io.cpp index 26dfebe..fe7dd4b 100644 --- a/moves_io.cpp +++ b/moves_io.cpp @@ -158,26 +158,26 @@ template Move uciToMove(const _Position &pos, std return move; } template /** - * @brief Parses a SAN string and resolves it to a legal move for the given position. - * - * Parses standard algebraic notation (including castling forms, captures, promotions, - * disambiguation by file/rank/source square, and optional trailing check/mate markers) - * and returns the corresponding legal Move for the position. When enabled via - * `remove_illegals`, the function will iteratively trim trailing characters and retry - * parsing to attempt recovery from malformed inputs. - * - * @param pos The position against which SAN is parsed and validated. - * @param raw_san The SAN string to parse (e.g. "Nbd2", "e8=Q", "O-O"). - * @param remove_illegals If true, attempt progressive trimming of the SAN on failure - * and accept the first parsable legal move. - * @return Move The matching legal move for the SAN, or `Move::none()`/`Move::null()` - * when no move could be produced (in builds/configurations where exceptions - * are disabled). - * - * @throws IllegalMoveException If the SAN is malformed or does not correspond to any - * legal move for the position. - * @throws AmbiguousMoveException If the SAN matches more than one legal move. - */ + * @brief Parses a SAN string and resolves it to a legal move for the given position. + * + * Parses standard algebraic notation (including castling forms, captures, promotions, + * disambiguation by file/rank/source square, and optional trailing check/mate markers) + * and returns the corresponding legal Move for the position. When enabled via + * `remove_illegals`, the function will iteratively trim trailing characters and retry + * parsing to attempt recovery from malformed inputs. + * + * @param pos The position against which SAN is parsed and validated. + * @param raw_san The SAN string to parse (e.g. "Nbd2", "e8=Q", "O-O"). + * @param remove_illegals If true, attempt progressive trimming of the SAN on failure + * and accept the first parsable legal move. + * @return Move The matching legal move for the SAN, or `Move::none()`/`Move::null()` + * when no move could be produced (in builds/configurations where exceptions + * are disabled). + * + * @throws IllegalMoveException If the SAN is malformed or does not correspond to any + * legal move for the position. + * @throws AmbiguousMoveException If the SAN matches more than one legal move. + */ Move parseSan(const _Position &pos, std::string_view raw_san, bool remove_illegals) { auto do_parse = [&](std::string_view input_san) -> Move { if (input_san.empty()) diff --git a/position.h b/position.h index ac7fa23..d6a855e 100644 --- a/position.h +++ b/position.h @@ -26,14 +26,15 @@ #include #include /** - * Compute origin squares of pieces of a given color that attack a target square using the supplied occupancy. - * - * @param color Attacking color. - * @param square Target square being attacked. - * @param occupied Bitboard representing board occupancy used for sliding-attack calculations; the result is intersected with this occupancy. - * @return Bitboard with squares of pieces of `color` that attack `square`, masked by `occupied`. - */ - namespace chess { + * Compute origin squares of pieces of a given color that attack a target square using the supplied occupancy. + * + * @param color Attacking color. + * @param square Target square being attacked. + * @param occupied Bitboard representing board occupancy used for sliding-attack calculations; the result is intersected with + * this occupancy. + * @return Bitboard with squares of pieces of `color` that attack `square`, masked by `occupied`. + */ +namespace chess { template struct alignas(64) HistoryEntry { // Bitboards for each piece type (white and black) diff --git a/tests.cpp b/tests.cpp index 1c2d1e7..55de829 100644 --- a/tests.cpp +++ b/tests.cpp @@ -198,22 +198,27 @@ template struct TestEntry { InputT input; CheckInfo info; }; -template /** - * @brief Count leaf nodes in the move tree from a given position to a specified depth. - * - * Performs a full recursive enumeration of legal moves using the MoveGenType template parameter and - * returns the total number of leaf positions reachable exactly `depth` plies from `pos`. - * - * The function mutates `pos` while exploring moves but always restores it to its original state before returning. - * - * @tparam T Position representation type. - * @tparam mt Move generation type controlling which moves are generated. - * @tparam EnableDiv When true, prints per-move node counts and the total to stdout. - * @param pos Position to enumerate from; will be restored to its initial state on return. - * @param depth Number of plies to explore; 0 yields 1 (the current position), 1 yields the number of legal moves. - * @return uint64_t Number of leaf nodes reachable at the given depth. - */ -uint64_t perft(_Position &pos, int depth) { +template /** + * @brief Count leaf nodes in the move tree from a given position to a specified depth. + * + * Performs a full recursive enumeration of legal moves using the MoveGenType template + * parameter and returns the total number of leaf positions reachable exactly `depth` plies + * from `pos`. + * + * The function mutates `pos` while exploring moves but always restores it to its original + * state before returning. + * + * @tparam T Position representation type. + * @tparam mt Move generation type controlling which moves are generated. + * @tparam EnableDiv When true, prints per-move node counts and the total to stdout. + * @param pos Position to enumerate from; will be restored to its initial state on return. + * @param depth Number of plies to explore; 0 yields 1 (the current position), 1 yields the + * number of legal moves. + * @return uint64_t Number of leaf nodes reachable at the given depth. + */ + uint64_t perft(_Position &pos, int depth) { if (depth == 0) { return 1; } else if (depth == 1) {