From 4fc7e8d76525255c001638c6f48c49dcd9f56609 Mon Sep 17 00:00:00 2001 From: Paul-Nicolas Madelaine Date: Wed, 26 Nov 2025 23:03:23 +0100 Subject: [PATCH] update documentation --- src/lib.rs | 13 ++++++------- src/moves.rs | 4 ++-- src/position.rs | 18 +++++++++--------- src/setup.rs | 11 ++++++----- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 1cfd376..f921760 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -8,13 +8,12 @@ //! In eschac, a chess position is represented with the [`Position`](position::Position) type. //! [`Position::new`](position::Position::new) returns the starting position of a chess game, and //! arbitrary positions can be built using the [`Setup`](setup::Setup) type. This type must be -//! validated and converted to a [`Position`](position::Position) to generate moves as eschac does -//! not handle certain unreachable positions (see -//! [`Setup::into_position`](setup::Setup::into_position) to know more). Legal moves are generated -//! using the [`Position::legal_moves`](position::Position::legal_moves) method or obtained from -//! chess notation like [`UciMove`](uci::UciMove) or [`San`](san::San). Moves are represented with -//! the [`Move<'l>`](moves::Move) type, which holds a reference to the origin position (this -//! ensures the move is played on the correct position). Finally, moves are played with +//! validated and converted to [`Position`](position::Position) with +//! [`Setup::into_position`](setup::Setup::into_position). Legal moves are generated using the +//! [`Position::legal_moves`](position::Position::legal_moves) method or obtained from chess +//! notation like [`UciMove`](uci::UciMove) or [`San`](san::San). Moves are represented with the +//! [`Move<'l>`](moves::Move) type, which holds a reference to the origin position to ensure that +//! the move is not played on another one. Finally, moves are played with //! [`Move::make`](moves::Move::make) which returns a new [`Position`](position::Position), and on //! it goes. //! diff --git a/src/moves.rs b/src/moves.rs index 0db6324..27b5a8a 100644 --- a/src/moves.rs +++ b/src/moves.rs @@ -205,8 +205,8 @@ impl<'l> Move<'l> { /// [composition](https://lichess.org/editor/R6R/3Q4/1Q4Q1/4Q3/2Q4Q/Q4Q2/pp1Q4/kBNN1KB1_w_-_-_0_1) /// with 218 legal moves. 60 years later, this was proven to be optimal by /// [Tobs40](https://lichess.org/@/Tobs40/blog/why-a-reachable-position-can-have-at-most-218-playable-moves/a5xdxeqs). -/// Even though the [`Position`] type can represent more positions than just reachable positions, -/// the proof still holds, as its definition of a position is even less restrictive. +/// Even though the [`Position`] type can represent some unreachable positions the proof still +/// holds, as its definition of a position is even less restrictive. #[must_use] #[derive(Clone)] pub struct Moves<'l> { diff --git a/src/position.rs b/src/position.rs index 4753dec..6277c65 100644 --- a/src/position.rs +++ b/src/position.rs @@ -38,9 +38,9 @@ use core::ops::ControlFlow; /// to playable moves. /// /// Playing a move is done through a copy-make interface. [`legal_moves`](Position::legal_moves) -/// returns a sequence of [`Move<'l>`](Move) objects. Moves hold a reference to the position -/// from where they were computed. They can be played without further checks and without potential -/// panics using [`Move::make`]. +/// returns a list of [`Move<'l>`](Move) objects. Moves hold a reference to the position from where +/// they were computed. They can be played without further checks and without potential panics +/// using [`Move::make`]. /// /// ## En passant & Equality /// @@ -98,13 +98,13 @@ impl Position { }) } - /// Returns the list of legal moves. + /// Returns the list of legal moves from the position. #[inline] pub fn legal_moves<'l>(&'l self) -> Moves<'l> { Moves::compute(self) } - /// Returns the number of legal moves. + /// Returns the number of legal moves from the position. #[must_use] #[inline] pub fn count_legal_moves(&self) -> usize { @@ -197,7 +197,7 @@ impl Position { self.generate_moves(&mut moves).is_break() } - /// Discards the en passant target square. + /// Removes the en passant target square, if any. /// /// This function will remove the en passant target square even if taking en passant is legal. /// If this is not desirable, it is the caller's responsibility to rule out the legality of en @@ -207,19 +207,19 @@ impl Position { self.0.en_passant = OptionSquare::None; } - /// Discards the castling rights for the given color and side. + /// Removes the castling rights for the given color and side, if any. #[inline] pub fn remove_castling_rights(&mut self, color: Color, side: CastlingSide) { self.0.set_castling_rights(color, side, false); } - /// Borrows the position as a [`Setup`]. + /// Converts the position to the [`Setup`] type. #[inline] pub fn as_setup(&self) -> &Setup { &self.0 } - /// Converts the position into the [`Setup`] type, allowing to edit it without enforcing its legality. + /// Converts the position to the [`Setup`] type. #[inline] pub fn into_setup(self) -> Setup { self.0 diff --git a/src/setup.rs b/src/setup.rs index cf4c57b..4be387c 100644 --- a/src/setup.rs +++ b/src/setup.rs @@ -315,11 +315,11 @@ impl Setup { /// Returns the quad-bitboard representation of the board. /// - /// This returns, in order: - /// - the squares occupied by the pawns, bishops and queens - /// - the squares occupied by the knights, bishops and kings - /// - the squares occupied by the rooks, queens and kings - /// - the squares occupied by the white pieces + /// This returns, in order, the squares occpied by: + /// - pawns, bishops and queens + /// - knights, bishops and kings + /// - rooks, queens and kings + /// - white pieces #[inline] pub fn bitboards(&self) -> [Bitboard; 4] { self.bitboards @@ -668,6 +668,7 @@ impl core::fmt::Display for IllegalPositionReason { /// An error when trying to parse a position record. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct ParseRecordError { + /// The index where the error was detected. pub byte: usize, } impl core::fmt::Display for ParseRecordError {