gnugo-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Trevor Morris
Subject: Re: [gnugo-devel] doc patch and structure discussion
Date: Sat, 23 Mar 2002 16:09:56 -0500

At 08:23 PM 3/23/2002 +0100, Gunnar Farneback wrote:
>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've only rarely consulted the documentation to see the function information.
However:
 1) I've toyed with generating Windows style help for the documentation, so I
might be tempted in the future.
 2) Why not generate the appropriate *.texi files directly from the source using
sed, awk or perl?  If no one uses it, it's certainly not worth the effort.






reply via email to

[Prev in Thread] Current Thread [Next in Thread]