From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 27050 invoked by alias); 7 Oct 2004 14:48:54 -0000 Mailing-List: contact gdb-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sources.redhat.com Received: (qmail 27036 invoked from network); 7 Oct 2004 14:48:52 -0000 Received: from unknown (HELO takamaka.act-europe.fr) (142.179.108.108) by sourceware.org with SMTP; 7 Oct 2004 14:48:52 -0000 Received: by takamaka.act-europe.fr (Postfix, from userid 507) id 2BCB647D98; Thu, 7 Oct 2004 07:48:52 -0700 (PDT) Date: Thu, 07 Oct 2004 15:12:00 -0000 From: Joel Brobecker To: Dave Korn Cc: 'Eli Zaretskii' , 'Andrew Cagney' , gdb@sources.redhat.com Subject: Re: Discussion: Formalizing the deprecation process in GDB Message-ID: <20041007144852.GG1282@gnat.com> References: <20041007024047.GB1282@gnat.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.4i X-SW-Source: 2004-10/txt/msg00214.txt.bz2 (this discussion about the internals documentation is for the purpose of formalizing the deprecation mechanism) > > I do agree with Andrew that the place were developers search > > for documentation is the code. > > Not me! I look for the internals docs! And complain bitterly when I > can't find them (because they don't exist) or they're years out of date! Well, one of the contributing factors of docs guetting out of date is that they are out of the developer's view. You can thank Eli for his tremendous job at keeping the gdbint doc in great shape, but also alerting us when some documentation needs to be added/modified in that manual. But in any case, my point was not that we should get rid of the internals manual entirely. There are parts that are more useful in this manual rather than the in the code. Parts that explain the big pictures, for instance, how everything fits together, etc. However, sections such as the section that explain what observers are, which ones are implemented, and what they should be used for, in my opinion, should be documented in the code. (actually, now that I think of it, the observer code is now generated from the doc - but I'm sure I can find other examples). -- Joel