From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5666 invoked by alias); 7 Oct 2004 12:42:48 -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 5637 invoked from network); 7 Oct 2004 12:42:46 -0000 Received: from unknown (HELO NUTMEG.CAM.ARTIMI.COM) (217.40.111.177) by sourceware.org with SMTP; 7 Oct 2004 12:42:46 -0000 Received: from mace ([192.168.1.25]) by NUTMEG.CAM.ARTIMI.COM with Microsoft SMTPSVC(6.0.3790.0); Thu, 7 Oct 2004 13:42:25 +0100 From: "Dave Korn" To: "'Joel Brobecker'" , "'Eli Zaretskii'" Cc: "'Andrew Cagney'" , Subject: RE: Discussion: Formalizing the deprecation process in GDB Date: Thu, 07 Oct 2004 14:27:00 -0000 MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit In-Reply-To: <20041007024047.GB1282@gnat.com> Message-ID: X-OriginalArrivalTime: 07 Oct 2004 12:42:25.0048 (UTC) FILETIME=[18C86180:01C4AC6B] X-SW-Source: 2004-10/txt/msg00207.txt.bz2 > -----Original Message----- > From: gdb-owner On Behalf Of Joel Brobecker > Sent: 07 October 2004 03:41 > 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! > This does not mean that I am suggesting that we get rid of gdbint > entirely. I see chapters and sections that can only be placed in > a separate documentation, such as how to add support for a new > host for instance. But the documentation about partial symbol > tables, for instance, would be much more useful directly in > symtab.h or symtab.c. Ok, I also read the code, but I very much appreciate having good documentation in book format. If you've got a serious chunk of architecture to learn about, it's a lot easier if it's all in one file that you can print out and browse through at your leisure rather than a page here and a page there scattered across many files. FWIW I reckon gcc is getting it very right these days. There's a heavyweight internals manual that explains the architecture and big picture issues. Each file that implements a substantial module of functionality then also has documentation about its internals and implementation at the top of the file. Usually you only need the internals manual, and only if you find yourself rummaging around in the depths of alias analysis or something chasing a bug do you find yourself needing the per-file-internal documentation. > I don't know about others, but I have read the gdbint manual once > from cover to cover almost 4 years ago, and never refered to it > anymore. Since opinions are being invited, I'll just mention that I'm currently working on an internal version of gdb for which I'm having to up-port a 5.x-compatible backend to 6.x series. I sometimes find it *ever* so hard when faced with yet another deprecated__ this or obsoleted_ that to know what the new and approved replacement is, and it often takes a combination of the internals manual, the in-source documentation and comments, and much searching of the list archive for the actual patch that made the deprecation to see how it was done at the time and understand the background and reasoning to it. I understand the reasons for using this technique and agree that it's sound engineering practice and necessary for the onward development of gdb, but I would like an easier solution to the general problem of knowing what to replace something with, and one that could be used off-line or on those occasions when sourceware goes down and you can't get at the list archive! cheers, DaveK -- Can't think of a witty .sigline today....