[gnugo-devel] Doc patch

[Gunnar Farneback]

Here's a doc patch which I didn't manage to finish in time for 3.4. It
updates the roadmap to the files in the engine directory. Feel free to
improve the descriptions. This patch does not take Arend's latest
restructuring of the boardlib code into account.

/Gunnar

Index: doc/overview.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/overview.texi,v
retrieving revision 1.17
diff -u -r1.17 overview.texi
--- doc/overview.texi   15 Jul 2003 22:29:19 -0000      1.17
+++ doc/overview.texi   11 Aug 2003 18:16:39 -0000
@@ -412,29 +412,51 @@
 stack. At the same time vital information such as the number of
 liberties for each string and their location is updated incrementally. 
 @end quotation
address@hidden @file{clock.c}
address@hidden @file{breakin.c}
address@hidden
+Code to detect moves which can break into supposed territory and moves
+to prevent this.
address@hidden quotation
address@hidden @file{cache.c} and @file{cache.h}
address@hidden
+As a means of speeding up reading, computed results are cached so that
+they can be quickly reused if the same position is encountered through
+e.g. another move ordering. This is implemented using a hash table.
address@hidden quotation
address@hidden @file{clock.c} and @file{clock.h}
 @quotation
 Clock code, including code allowing GNU Go to automatically
 adjust its level in order to avoid losing on time in tournaments.
 @end quotation
address@hidden @file{combination.c}
address@hidden
+When something can (only) be captured through a series of ataris or
+other threats we call this a combination attack. This file contains code
+to find such attacks and moves to prevent them.
address@hidden quotation
 @item @file{dragon.c}
 @quotation
 This contains @code{make_dragons()}. This function is executed before
 the move-generating modules @code{shapes()} @code{semeai()} and the
-other move generators but after @code{make_worms}. It tries to connect
+other move generators but after @code{make_worms()}. It tries to connect
 worms into dragons and collect important information about them, such as
 how many liberties each has, whether (in GNU Go's opinion) the dragon
 can be captured, if it lives, etc.
 @end quotation
address@hidden @file{fuseki.c}
address@hidden @file{endgame.c}
 @quotation
-Generates fuseki (opening) moves from a database.
+Code to find certain types of endgame moves.
 @end quotation
 @item @file{filllib.c}
 @quotation 
 Code to force filling of dame (backfilling if necessary)
 at the end of the game.
 @end quotation
address@hidden @file{fuseki.c}
address@hidden
+Generates fuseki (opening) moves from a database. Also generates moves
+in empty corners.
address@hidden quotation
 @item @file{genmove.c}
 @quotation
 This file contains @code{genmove()} and its supporting
@@ -449,21 +471,12 @@
 This file contains declarations forming the public interface to
 the engine.
 @end quotation
address@hidden @file{hash.c} and @file{cache.c}
address@hidden @file{hash.c} and @file{hash.h}
 @quotation
 Hashing code implementing Zobrist hashing. (@pxref{Hashing}) The code in
 @file{hash.c} provides a way to hash board positions into compact descriptions
-which can be efficiently compared. The code in @file{cache.c} implements a
-kind of database for storing reading results, so they can be quickly
-retrieved. The caching code uses the board hashes as keys to the database.
-They are split since these functionalities are sufficiently demarked that
-either file could be reimplemented without affecting the other one.  Note also
-that @code{matchpat()} uses the hashing code without also using the caching
-code.
address@hidden quotation
address@hidden @file{hash.h} and @file{cache.h}
address@hidden
-Header files for @file{hash.c} and @file{cache.c}.
+which can be efficiently compared. The caching code in @file{cache.c}
+makes use of the board hashes when storing and retrieving read results.
 @end quotation
 @item @file{influence.c} and @file{influence.h}.
 @quotation
@@ -483,26 +496,46 @@
 the @file{patterns/} directory. The function @code{matchpat()} is
 called by every module which does pattern matching, notably @code{shapes}.
 @end quotation
address@hidden @file{move_reasons.c}
address@hidden @file{move_reasons.c} and @file{move_reasons.h}
 @quotation
-This file contains the code which assigns values to every move
-after all the move reasons are gen
+Code for keeping track of move reasons.
address@hidden quotation
address@hidden @file{movelist.c}
address@hidden 
+Supporting code for lists of moves.
 @end quotation
 @item @file{optics.c}
 @quotation 
 This file contains the code to recognize eye shapes,
 documented in @xref{Eyes}.
 @end quotation
address@hidden @file{oracle.c}
address@hidden 
+Code to fork off a second GNU Go process which can be used to simulate
+reading with top level information (e.g. dragon partitioning) available.
address@hidden quotation
 @item @file{owl.c}
 @quotation
-This file does life and death reading. The paradigm is that moves
-are played by both players trying to expand and shrink the eyespace
-until a static configuration is reached where it can be analyzed
-by the code in @file{optics.c}.
+This file does life and death reading. Move generation is pattern based
+and the code in @file{optics.c} is used to evaluate the eyespaces for
+vital moves and independent life. A dragon can also live by successfully
+escaping. Semeai reading along the same principles is also implemented
+in this file.
address@hidden quotation
address@hidden @file{persistent.c}
address@hidden
+Persistent cache which allows reuse of read results at a later move or
+with additional stones outside an active area, which are those
+intersections thought to affect the read result.
 @end quotation
 @item @file{printutils.c}
 @quotation
-Print utilities
+Print utilities.
address@hidden quotation
address@hidden @file{readconnect.c} and @file{readconnect.h}
address@hidden 
+This file contains code to determine whether two strings can be
+connected or disconnected.
 @end quotation
 @item @file{reading.c}
 @quotation 
@@ -517,9 +550,13 @@
 @end quotation
 @item @file{semeai.c}
 @quotation 
-This file contains @code{semeai()}, the module which tries to
-win capturing races. This module does not work particularly
-well and will eventually be replaced.
+This file contains @code{semeai()}, the module which detects dragons
+in semeai. To determine the semeai results the semeai reading in
address@hidden is used.
address@hidden quotation
address@hidden @file{sgfdecide.c}
address@hidden 
+Code to generate sgf traces for various types of reading.
 @end quotation
 @item @file{shapes.c}
 @quotation 
@@ -534,16 +571,27 @@
 primary interface in GNU Go 1.2, but is now a debugging 
 aid.
 @end quotation
address@hidden @file{surround.c}
address@hidden 
+Code to determine whether a dragon is surrounded and to find moves to
+surround with or break out with.
address@hidden quotation
address@hidden @file{utils.c}
address@hidden
+An assortment of utilities, described in greater detail below.
address@hidden quotation
address@hidden @file{value_moves.c}
address@hidden 
+This file contains the code which assigns values to every move
+after all the move reasons are generated. It also tries to generate
+certain kinds of additional move reasons.
address@hidden quotation
 @item @file{worm.c}
 @quotation 
 This file contains @code{make_worms()}, code which is run at the
 beginning of each move cycle, before the code in @file{dragon.c}, to
 determine the attributes of every string. These attributes are things
 like liberties, wether the string can be captured (and how), etc
address@hidden quotation
address@hidden @file{utils.c}
address@hidden
-An assortment of utilities, described in greater detail below.
 @end quotation
 @end itemize