📝 Add docstrings to 52-unneeded-parameters-in-function

moves_io.cpp

@@ -157,7 +157,28 @@ template <typename T, typename V> Move uciToMove(const _Position<T, V> &pos, std
 #endif
     return move;
 }
-template <typename T, typename P> Move parseSan(const _Position<T, P> &pos, std::string_view raw_san, bool remove_illegals) {
+template <typename T, typename P> /**
+                                   * @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<T, P> &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();

position.h

@@ -25,6 +25,15 @@
 #include <stdexcept>
 #include <string>
 #include <vector>
+/**
+ * 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 <typename Piece> struct alignas(64) HistoryEntry {

tests.cpp

@@ -198,7 +198,27 @@ template <typename InputT, typename CheckInfo> struct TestEntry {
     InputT input;
     CheckInfo info;
 };
-template <typename T, MoveGenType mt, bool EnableDiv = false> uint64_t perft(_Position<T> &pos, int depth) {
+template <typename T,
+          MoveGenType mt,
+          bool EnableDiv = false> /**
+                                   * @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<T> &pos, int depth) {
     if (depth == 0) {
         return 1;
     } else if (depth == 1) {

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<T>::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,