From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30113 invoked by alias); 8 Oct 2004 10:10:29 -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 30103 invoked from network); 8 Oct 2004 10:10:27 -0000 Received: from unknown (HELO legolas.inter.net.il) (192.114.186.24) by sourceware.org with SMTP; 8 Oct 2004 10:10:27 -0000 Received: from zaretski (pns03-208-187.inter.net.il [80.230.208.187]) by legolas.inter.net.il (MOS 3.5.3-GR) with ESMTP id CTV15794 (AUTH halo1); Fri, 8 Oct 2004 12:10:21 +0200 (IST) Date: Fri, 08 Oct 2004 10:38:00 -0000 From: "Eli Zaretskii" To: Joel Brobecker Message-ID: <01c4ad1e$Blat.v2.2.2$b23294e0@zahav.net.il> Content-Transfer-Encoding: 7BIT Content-Type: text/plain; charset=ISO-8859-1 CC: cagney@gnu.org, gdb@sources.redhat.com In-reply-to: <20041007024047.GB1282@gnat.com> (message from Joel Brobecker on Wed, 6 Oct 2004 19:40:48 -0700) Subject: Re: Discussion: Formalizing the deprecation process in GDB Reply-to: Eli Zaretskii References: <20040927175539.GS974@gnat.com> <41637DBD.8030209@gnu.org> <01c4aba7$Blat.v2.2.2$141c3ea0@zahav.net.il> <20041007024047.GB1282@gnat.com> X-SW-Source: 2004-10/txt/msg00245.txt.bz2 > Date: Wed, 6 Oct 2004 19:40:48 -0700 > From: Joel Brobecker > Cc: Andrew Cagney , gdb@sources.redhat.com > > I do agree with Andrew that the place were developers search > for documentation is the code. I would love to see a lot of the > documentation contained in gdbint.texinfo be moved as comments > into the code. Having the documentation embedded inside the code > is very convenient, and also where I have been trained to look > first. > > 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. The problem with having documentation in the code is that there's no easy way of organizing such a documentation: no cross-references, no chapter/section/subsection structure, and no index. For someone who is on the learning curve looking for a more-or-less complete description of a specific GDB mechanism, let alone a high-level architectural overview, these disadvantages are IMO significant and grave. In addition, code comments in many cases have a loophole view of the code, and so higher-level aspects tend to be not documented at all. Code comments are also not reviewed as formally as docs submissions are. As an illustration to these deficiencies, please see how many questions we have on this mailing list asking to explain how some specific GDB feature works, and how they are almost _never_ answered by pointing people to the code comments, nor to the docs. Does anyone need a better demonstration of the fact that our code is largely undocumented? If we are willing to move in the direction of making the docs and the code closer (and assuming volunteers will step forward to do the job), we could look at the various systems that generate code and manuals from the same source. Failing that, I'd rather support having _more_ of the explanations in the manual and less in the comments, and adding references in the comments to relevant gdbint.texinfo places. I think that on balance this is a better alternative than the opposite one, where we prefer comments to Texinfo docs. > 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. That is simply because of the poor quality (in terms of coverage of the relevant subject matter) of gdbint.texinfo. We should do much better.