Re: [gnugo-devel] doc patch and structure discussion

[Gunnar Farneback]

Dan wrote:
> They shouldn't be out of date. I updated most of them in the last
> few weeks. 

Currently they seem to be mostly up to date, but that is not how
things have been most of the time.

> The function descriptions generally duplicate what is in the
> source code. Having them there means that the documentation is
> complete in the sense that you can look a function up in the index
> and find out something about it. Or you can browse the list of
> public functions in board.c and find out what they are without
> having to wade through masses of intervening code and statically
> declared functions. This seems to me to be useful but if everyone
> wants them taken out we can discuss it.

The basic problem with this is that it breaks the principle of having
each piece of information in exactly one place. With multiple sources
of information we get two problems:
1. It requires much work to maintain the consistency.
2. Things *will* get out of sync.

I have never looked up a function in the docs. For me it's both faster
and more reliable to look directly in the code. But to be fair I don't
think I have read any documentation at all since before 2.0 for other
purposes than to revise it.

> > I can help with all this, but of course I will address the code/tuning
> > matters that I want to do first.
> 
> Right, at the moment you have two projects (influence and hash) more
> urgent than doc revision. Doc revision is a good thing to work on during the
> code freeze before the release.

I intend to restructure the board documentation and write (at least) a
draft for a revised overview chapter.

/Gunnar