update documentation

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
+//! validated and converted to [`Position`](position::Position) with
-//! not handle certain unreachable positions (see
+//! [`Setup::into_position`](setup::Setup::into_position). Legal moves are generated using the
-//! [`Setup::into_position`](setup::Setup::into_position) to know more). Legal moves are generated
+//! [`Position::legal_moves`](position::Position::legal_moves) method or obtained from chess
-//! using the [`Position::legal_moves`](position::Position::legal_moves) method or obtained from
+//! notation like [`UciMove`](uci::UciMove) or [`San`](san::San). Moves are represented with the
-//! chess notation like [`UciMove`](uci::UciMove) or [`San`](san::San). Moves are represented with
+//! [`Move<'l>`](moves::Move) type, which holds a reference to the origin position to ensure that
-//! the [`Move<'l>`](moves::Move) type, which holds a reference to the origin position (this
+//! the move is not played on another one. Finally, moves are played with
-//! ensures the move is played on the correct position). Finally, moves are played with
 //! [`Move::make`](moves::Move::make) which returns a new [`Position`](position::Position), and on
 //! it goes.
 //!

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,
+/// Even though the [`Position`] type can represent some unreachable positions the proof still
-/// the proof still holds, as its definition of a position is even less restrictive.
+/// holds, as its definition of a position is even less restrictive.
 #[must_use]
 #[derive(Clone)]
 pub struct Moves<'l> {

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
+/// returns a list of [`Move<'l>`](Move) objects. Moves hold a reference to the position from where
-/// from where they were computed. They can be played without further checks and without potential
+/// they were computed. They can be played without further checks and without potential panics
-/// panics using [`Move::make`].
+/// 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

src/setup.rs

@@ -315,11 +315,11 @@ impl Setup {
 
     /// Returns the quad-bitboard representation of the board.
     ///
-    /// This returns, in order:
+    /// This returns, in order, the squares occpied by:
-    /// - the squares occupied by the pawns, bishops and queens
+    /// - pawns, bishops and queens
-    /// - the squares occupied by the knights, bishops and kings
+    /// - knights, bishops and kings
-    /// - the squares occupied by the rooks, queens and kings
+    /// - rooks, queens and kings
-    /// - the squares occupied by the white pieces
+    /// - 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 {