From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3381 invoked by alias); 7 Oct 2004 17:50:51 -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 3363 invoked from network); 7 Oct 2004 17:50:49 -0000 Received: from unknown (HELO NUTMEG.CAM.ARTIMI.COM) (217.40.111.177) by sourceware.org with SMTP; 7 Oct 2004 17:50:49 -0000 Received: from mace ([192.168.1.25]) by NUTMEG.CAM.ARTIMI.COM with Microsoft SMTPSVC(6.0.3790.0); Thu, 7 Oct 2004 18:50:26 +0100 From: "Dave Korn" To: "'Andrew Cagney'" , "'Joel Brobecker'" , "'Eli Zaretskii'" Cc: Subject: RE: Discussion: Formalizing the deprecation process in GDB Date: Thu, 07 Oct 2004 18:50:00 -0000 MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit In-Reply-To: <4165656B.4070007@gnu.org> Message-ID: X-OriginalArrivalTime: 07 Oct 2004 17:50:26.0876 (UTC) FILETIME=[20CF87C0:01C4AC96] X-SW-Source: 2004-10/txt/msg00227.txt.bz2 > -----Original Message----- > From: Andrew Cagney > Sent: 07 October 2004 16:49 > To: Joel Brobecker; Dave Korn; 'Eli Zaretskii' > >>>> > 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! It's just occurred to me that this could be read as a specific complaint or accusation against gdb's documentation, rather than a comment on the generally sorry state of documentation as a whole in the software industry. No such inference was implied nor intended; sorry if anyone thought I was criticising gdb with that statement! > > Well, one of the contributing factors of docs guetting out of date > > is that they are out of the developer's view. Things like the doxygen format are good for that: you keep the doco for (eg) a function right inline with the code, so it stands a good chance of being kept up-to-date whenever anyone works on that bit of code, but then there's an automated process that gathers all the documentation from its many-and-widely-scattered locations in the source, and compiles it into one nice neat help file. I mention it because I think it's a good idea, but have to say that I can't see any way it could be reasonably retrofitted to a project on the scale of gdb, so I'm not sure if it was even worth mentioning except out of academic interest.... > "gdbarch.sh", "target.h", "inferior.h", ... are all better examples. > For those, my things to do one day include get them into a format > similar to observer.texi so that at least the interface is > single source. ... although maybe it could be useful in limited areas of application such as this one! Thing is, coming newly to gdb, there isn't even anything to tell you to look in any of those files. It can be quite disheartening when you read "This section is pretty much obsolete. The functionality described here has largely been replaced by pseudo-registers and the mechanisms described in Chapter 9 [Using Different Register and Memory Data Representations], page 30." and you go to the reference and see "The way GDB manipulates registers is undergoing significant change. Many of the macros and functions refered to in this section are likely to be subject to further revision." and then you're left wondering "Well, what revision? Which macros and functions? What should I actually _do_ about this?". Or when you see lots of things to do with registers have been deprecated, and there's this new high-level mechanism called regcache, which is some kind of cache of the inferiors registers, but there's no overview of the new scheme anywhere - or at any rate, not in regcache.[ch]. Part of my problem is undoubtedly just unfamiliarity with the code, so take my opinions on this matter as relating particularly to the situation for someone getting to grips with gdb's sources for the first time: it's very hard to break into. > I think separate documentation is good for recording > processes such as > releasing gdb or version numbers; and higher level architecture and > perhaps even some medium level models (showing how it is ment > to be not > how bu----ed it currently is :-). Heh, basically this is indeed what I'm wishing for. cheers, DaveK -- Can't think of a witty .sigline today....