documentation tweaks and updates

niklasf · niklasf · commit e0be0b45e66d · 2019-01-09T17:49:21.000+01:00
diff --git a/chess/engine.py b/chess/engine.py
@@ -665,13 +665,14 @@ def play(self, board, limit, *, game=None, info=INFO_NONE, ponder=False, root_mo
 
         :param board: The position. The entire move stack will be sent to the
             engine.
-        :param limit: An instance of :class:`~chess.engine.Limit` that
+        :param limit: An instance of :class:`chess.engine.Limit` that
             determines when to stop thinking.
         :param game: Optional. An arbitrary object that identifies the game.
-            Will automatically clear hashtables if the object is not equal
-            to the previous game.
+            Will automatically inform the engine if the object is not equal
+            to the previous game (e.g. ``ucinewgame``, ``new``).
         :param info: Selects which additional information to retrieve from the
-            engine. ``INFO_NONE``, ``INFO_BASE``, ``INFO_SCORE``, ``INFO_PV``,
+            engine. ``INFO_NONE``, ``INFO_BASE`` (basic information that is
+            trivial to obtain), ``INFO_SCORE``, ``INFO_PV``,
             ``INFO_REFUTATION``, ``INFO_CURRLINE``, ``INFO_ALL`` or any
             bitwise combination. Some overhead is associated with parsing
             extra information.
@@ -687,20 +688,22 @@ def play(self, board, limit, *, game=None, info=INFO_NONE, ponder=False, root_mo
     @asyncio.coroutine
     def analyse(self, board, limit, *, multipv=None, game=None, info=INFO_ALL, root_moves=None, options={}):
         """
-        Analyses a position and returns an info dictionary.
+        Analyses a position and returns a dictionary of
+        `information <#chess.engine.PlayResult.info>`_.
 
         :param board: The position to analyse. The entire move stack will be
             sent to the engine.
-        :param limit: An instance of :class:`~chess.engine.Limit` that
+        :param limit: An instance of :class:`chess.engine.Limit` that
             determines when to stop the analysis.
         :param multipv: Optional. Analyse multiple root moves. Will return a list of
             at most *multipv* dictionaries rather than just a single
             info dictionary.
         :param game: Optional. An arbitrary object that identifies the game.
-            Will automatically clear hashtables if the object is not equal
-            to the previous game.
+            Will automatically inform the engine if the object is not equal
+            to the previous game (e.g. ``ucinewgame``, ``new``).
         :param info: Selects which information to retrieve from the
-            engine. ``INFO_NONE``, ``INFO_BASE``, ``INFO_SCORE``, ``INFO_PV``,
+            engine. ``INFO_NONE``, ``INFO_BASE`` (basic information that is
+            trivial to obtain), ``INFO_SCORE``, ``INFO_PV``,
             ``INFO_REFUTATION``, ``INFO_CURRLINE``, ``INFO_ALL`` or any
             bitwise combination. Some overhead is associated with parsing
             extra information.
@@ -725,15 +728,16 @@ def analysis(self, board, limit=None, *, multipv=None, game=None, info=INFO_ALL,
 
         :param board: The position to analyse. The entire move stack will be
             sent to the engine.
-        :param limit: Optional. An instance of :class:`~chess.engine.Limit`
+        :param limit: Optional. An instance of :class:`chess.engine.Limit`
             that determines when to stop the analysis. Analysis is infinite
             by default.
         :param multipv: Optional. Analyse multiple root moves.
         :param game: Optional. An arbitrary object that identifies the game.
             Will automatically clear hashtables if the object is not equal
             to the previous game.
         :param info: Selects which information to retrieve from the
-            engine. ``INFO_NONE``, ``INFO_BASE``, ``INFO_SCORE``, ``INFO_PV``,
+            engine. ``INFO_NONE``, ``INFO_BASE`` (basic information that is
+            trivial to obtain), ``INFO_SCORE``, ``INFO_PV``,
             ``INFO_REFUTATION``, ``INFO_CURRLINE``, ``INFO_ALL`` or any
             bitwise combination. Some overhead is associated with parsing
             extra information.
diff --git a/docs/engine.rst b/docs/engine.rst
@@ -1,20 +1,18 @@
-Engine communication [experimental]
+Engine communication (experimental)
 ===================================
 
 UCI and XBoard are protocols for communicating with chess engines. This module
 implements an abstraction for playing moves and analysing positions with
 both kinds of engines.
 
 :warning: This is an experimental module that may change in semver incompatible
-   ways. Please weigh in on the design if the provided APIs do not cover
-   your use case.
+   ways. Please `weigh in <https://github.com/niklasf/python-chess/issues/new>`_
+   on the design if the provided APIs do not cover your use case.
 
    The intention is to eventually replace ``chess.uci`` and ``chess.xboard``,
    but not before things have settled down and there has been a transition
    period.
 
-   The XBoard implementation is currently only a skeleton.
-
 The preferred way to use the API is with an
 `asyncio <https://docs.python.org/3/library/asyncio.html>`_ event loop.
 The examples also show a simple synchronous wrapper
@@ -35,7 +33,7 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 
     board = chess.Board()
     while not board.is_game_over():
-        result = engine.play(board, chess.engine.Limit(movetime=100))
+        result = engine.play(board, chess.engine.Limit(time=0.100))
         board.push(result.move)
 
     engine.quit()
@@ -51,7 +49,7 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 
         board = chess.Board()
         while not board.is_game_over():
-            result = await engine.play(board, chess.engine.Limit(movetime=100))
+            result = await engine.play(board, chess.engine.Limit(time=0.100))
             board.push(result.move)
 
         await engine.quit()
@@ -115,11 +113,16 @@ Example: Let Stockfish play against itself, 100 milliseconds per move.
 
     .. py:attribute:: info
 
-        A dictionary of extra information sent by the engine. Known keys are
-        ``score``, ``depth``, ``seldepth``, ``time``, ``nodes``, ``pv``,
-        ``multipv``, ``currmove``, ``currmovenumber``, ``hashfull``, ``nps``,
-        ``tbhits``, ``cpuload``, ``refutation``, ``currline``, ``ebf`` and
-        ``string``.
+        A dictionary of extra information sent by the engine. Commonly used
+        keys are: ``score``, ``pv``, ``depth``, ``seldepth``, ``time``
+        (in seconds), ``nodes``, ``nps``, ``tbhits``, ``multipv``.
+
+        Others: ``currmove``, ``currmovenumber``, ``hashfull``
+        ``cpuload``, ``refutation``, ``currline``, ``ebf`` and ``string``.
+
+    .. py:attribute:: draw_offered
+
+        Whether the engine offered a draw before moving.
 
 Analysing and evaluating a position
 -----------------------------------
@@ -134,7 +137,7 @@ Example:
     engine = chess.engine.SimpleEngine.popen_uci("stockfish")
 
     board = chess.Board()
-    info = engine.analyse(board, chess.engine.Limit(movetime=100))
+    info = engine.analyse(board, chess.engine.Limit(time=0.100))
     print("Score:", info["score"])
     # Score: +20
 
@@ -155,7 +158,7 @@ Example:
         transport, engine = await chess.engine.popen_uci("stockfish")
 
         board = chess.Board()
-        info = await engine.analyse(board, chess.engine.Limit(movetime=100))
+        info = await engine.analyse(board, chess.engine.Limit(time=0.100))
         print(info["score"])
         # Score: +20
 
