chess-polyglot.el: Docs + one assert.

1 files changed, 15 insertions, 6 deletions

diff --git a/chess-polyglot.el b/chess-polyglot.el
index 391320d..58f2f94 100644
--- a/chess-polyglot.el
+++ b/chess-polyglot.el
@@ -51,6 +51,7 @@
 
 (defcustom chess-polyglot-book-strength 1.0
   "Influence random distribution when picking a ply from the book.
+
 A value above 1.0 means to prefer known good moves while a value below
 1.0 means to penalize known good moves.  0.0 will force uniform
 distribution of move weights.  For reasons of numerical overflow,
@@ -59,10 +60,13 @@ this should be strictly less than 4.0."
   :type '(float :match (lambda (widget value) (and (>= value 0) (< value 4)))))
 
 (defvar chess-polyglot-book nil
-  "The default polyglot book object.")
+  "The default polyglot book object.
+
+This is automatically set if `chess-polyglot-book-file' points to a valid
+polyglot book file.")
 
 (defsubst chess-polyglot-read-octets (n)
-  "Read N octets from the current buffer."
+  "Read N octets from the current buffer and advance point."
   (let ((val 0))
     (dotimes (_ n (progn (cl-assert (<= val most-positive-fixnum)) val))
       (setq val (logior (lsh val 8)
@@ -90,7 +94,7 @@ The result is a list of the form (FROM-INDEX TO-INDEX PROMOTION WEIGHT)."
 
 (defun chess-polyglot-move-to-ply (position from to promotion weight)
   "Convert a polyglot move for POSITION to a ply.
-FROM and TO are integers indicating the square index.
+FROM and TO are integers indicating the square indices.
 PROMOTION, if non-nil, indicates the piece to promote to.
 WEIGHT (an integer) is the relative weight of the move."
   (cl-assert (vectorp position))
@@ -112,7 +116,7 @@ WEIGHT (an integer) is the relative weight of the move."
     ply))
 
 (defsubst chess-polyglot-skip-learn ()
-  "Skip the 32 bit learn value."
+  "Skip the (unused) 32 bit learn value."
   (forward-char 4))
 
 (defconst chess-polyglot-record-size 16
@@ -476,6 +480,7 @@ Returns a buffer object which contains the binary data."
 		   (`(,method ,_ ,modified-epoch ,_ ,from-fs)
 		    (and (= method 8) (> modified-epoch 0) (< from-fs 16)))))
 	(zlib-decompress-region (point-min) (point-max)))
+      (cl-assert (zerop (% (buffer-size) chess-polyglot-record-size)))
       (current-buffer))))
 
 (defun chess-polyglot-book-plies (book position)
@@ -525,13 +530,17 @@ distribute the probability that a move gets picked."
 (defun chess-polyglot-book-reload (symbol value)
   (set symbol value)
   (when (eq symbol 'chess-polyglot-book-file)
-    (setq chess-polyglot-book (chess-polyglot-book-open value))))
+    (setq chess-polyglot-book
+	  (when chess-polyglot-book-file
+	    (chess-polyglot-book-open chess-polyglot-book-file)))))
 
 (defcustom chess-polyglot-book-file (expand-file-name "chess-polyglot.bin"
 						      (file-name-directory
 						       (or load-file-name
 							   buffer-file-name)))
-  "Path to default polyglot book file."
+  "Path to default polyglot book file.
+
+This is used by UCI based engines as well as the internal AI."
   :group 'chess-polyglot
   :set 'chess-polyglot-book-reload
   :type '(file :must-match t))