Document that editing board clears move stack (fixes #887)

Author: niklasf

chess/__init__.py

@@ -623,7 +623,13 @@ def _reset_board(self) -> None:
         self.occupied = BB_RANK_1 | BB_RANK_2 | BB_RANK_7 | BB_RANK_8
 
     def reset_board(self) -> None:
-        """Resets pieces to the starting position."""
+        """
+        Resets pieces to the starting position.
+
+        :class:`~chess.Board` also resets the move stack, but not turn,
+        castling rights and move counters. Use :func:`chess.Board.reset()` to
+        fully restore the starting position.
+        """
         self._reset_board()
 
     def _clear_board(self) -> None:
@@ -641,7 +647,11 @@ def _clear_board(self) -> None:
         self.occupied = BB_EMPTY
 
     def clear_board(self) -> None:
-        """Clears the board."""
+        """
+        Clears the board.
+
+        :class:`~chess.Board` also clears the move stack.
+        """
         self._clear_board()
 
     def pieces_mask(self, piece_type: PieceType, color: Color) -> Bitboard:
@@ -877,6 +887,8 @@ def remove_piece_at(self, square: Square) -> Optional[Piece]:
         """
         Removes the piece from the given square. Returns the
         :class:`~chess.Piece` or ``None`` if the square was already empty.
+
+        :class:`~chess.Board` also clears the move stack.
         """
         color = bool(self.occupied_co[WHITE] & BB_SQUARES[square])
         piece_type = self._remove_piece_at(square)
@@ -914,6 +926,8 @@ def set_piece_at(self, square: Square, piece: Optional[Piece], promoted: bool =
 
         An existing piece is replaced. Setting *piece* to ``None`` is
         equivalent to :func:`~chess.Board.remove_piece_at()`.
+
+        :class:`~chess.Board` also clears the move stack.
         """
         if piece is None:
             self._remove_piece_at(square)
@@ -1010,6 +1024,8 @@ def set_board_fen(self, fen: str) -> None:
         Parses *fen* and sets up the board, where *fen* is the board part of
         a FEN.
 
+        :class:`~chess.Board` also clears the move stack.
+
         :raises: :exc:`ValueError` if syntactically invalid.
         """
         self._set_board_fen(fen)
@@ -1032,6 +1048,8 @@ def set_piece_map(self, pieces: Mapping[Square, Piece]) -> None:
         """
         Sets up the board from a dictionary of :class:`pieces <chess.Piece>`
         by square index.
+
+        :class:`~chess.Board` also clears the move stack.
         """
         self._set_piece_map(pieces)
 
@@ -1283,8 +1301,8 @@ def apply_transform(self, f: Callable[[Bitboard], Bitboard]) -> None:
 
     def transform(self: BaseBoardT, f: Callable[[Bitboard], Bitboard]) -> BaseBoardT:
         """
-        Returns a transformed copy of the board by applying a bitboard
-        transformation function.
+        Returns a transformed copy of the board (without move stack)
+        by applying a bitboard transformation function.
 
         Available transformations include :func:`chess.flip_vertical()`,
         :func:`chess.flip_horizontal()`, :func:`chess.flip_diagonal()`,
@@ -1305,7 +1323,7 @@ def apply_mirror(self: BaseBoardT) -> None:
 
     def mirror(self: BaseBoardT) -> BaseBoardT:
         """
-        Returns a mirrored copy of the board.
+        Returns a mirrored copy of the board (without move stack).
 
         The board is mirrored vertically and piece colors are swapped, so that
         the position is equivalent modulo color.
@@ -1582,11 +1600,6 @@ def reset(self) -> None:
         self.reset_board()
 
     def reset_board(self) -> None:
-        """
-        Resets only pieces to the starting position. Use
-        :func:`~chess.Board.reset()` to fully restore the starting position
-        (including turn, castling rights, etc.).
-        """
         super().reset_board()
         self.clear_stack()
 
@@ -2524,6 +2537,8 @@ def set_castling_fen(self, castling_fen: str) -> None:
         """
         Sets castling rights from a string in FEN notation like ``Qqk``.
 
+        Also clears the move stack.
+
         :raises: :exc:`ValueError` if the castling FEN is syntactically
             invalid.
         """

docs/core.rst

@@ -108,6 +108,7 @@ Board
 
 .. autoclass:: chess.Board
     :members:
+    :exclude-members: set_piece_at, remove_piece_at, reset_board, set_board_fen, set_piece_map, set_chess960_pos, apply_transform
 
 .. autoclass:: chess.BaseBoard
     :members: