Merge pull request #1023 from MarkZH/documentation

Engine communication documentation

Author: niklasf

chess/engine.py

@@ -449,10 +449,18 @@ class Info(enum.IntFlag):
 @dataclasses.dataclass
 class Opponent:
     """Used to store information about an engine's opponent."""
+
     name: Optional[str]
+    """The name of the opponent."""
+
     title: Optional[str]
+    """The opponent's title--for example, GM, IM, or BOT."""
+
     rating: Optional[int]
+    """The opponent's ELO rating."""
+
     is_engine: Optional[bool]
+    """Whether the opponent is a chess engine/computer program."""
 
 
 class PovScore:
@@ -1158,7 +1166,7 @@ async def send_opponent_information(self, *, opponent: Optional[Opponent] = None
         method should be called before the first move of a game--i.e., the
         first call to :func:`chess.engine.Protocol.play()`.
 
-        :param opponent: Optional. The opponent's information.
+        :param opponent: Optional. An instance of :class:`chess.engine.Opponent` that has the opponent's information.
         :param engine_rating: Optional. This engine's own rating. Only used by XBoard engines.
         """
 
@@ -1272,9 +1280,9 @@ async def send_game_result(self, board: chess.Board, winner: Optional[Color] = N
         Sends the engine the result of the game.
 
         XBoard engines receive the final moves and a line of the form
-        "result <winner> {<ending>}". The <winner> field is one of "1-0",
-        "0-1", "1/2-1/2", or "*" to indicate white won, black won, draw,
-        or adjournment, respectively. The <ending> field is a description
+        ``result <winner> {<ending>}``. The ``<winner>`` field is one of ``1-0``,
+        ``0-1``, ``1/2-1/2``, or ``*`` to indicate white won, black won, draw,
+        or adjournment, respectively. The ``<ending>`` field is a description
         of the specific reason for the end of the game: "White mates",
         "Time forfeiture", "Stalemate", etc.
 
@@ -1284,9 +1292,10 @@ async def send_game_result(self, board: chess.Board, winner: Optional[Color] = N
         :param board: The final state of the board.
         :param winner: Optional. Specify the winner of the game. This is useful
             if the result of the game is not evident from the board--e.g., time
-            forfeiture or draw by agreement.
+            forfeiture or draw by agreement. If not ``None``, this parameter
+            overrides any winner derivable from the board.
         :param game_ending: Optional. Text describing the reason for the game
-            ending. Similarly to the winner paramter, this overrides any game
+            ending. Similarly to the winner parameter, this overrides any game
             result derivable from the board.
         :param game_complete: Optional. Whether the game reached completion.
         """

docs/engine.rst

@@ -70,6 +70,15 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 .. autoclass:: chess.engine.PlayResult
     :members:
 
+.. autoclass:: chess.engine.Protocol
+    :members: send_opponent_information
+
+.. autoclass:: chess.engine.Opponent
+    :members:
+
+.. autoclass:: chess.engine.Protocol
+    :members: send_game_result
+
 Analysing and evaluating a position
 -----------------------------------