From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17978 invoked by alias); 7 Oct 2004 15:49:27 -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 17948 invoked from network); 7 Oct 2004 15:49:24 -0000 Received: from unknown (HELO mx1.redhat.com) (66.187.233.31) by sourceware.org with SMTP; 7 Oct 2004 15:49:24 -0000 Received: from int-mx1.corp.redhat.com (int-mx1.corp.redhat.com [172.16.52.254]) by mx1.redhat.com (8.12.11/8.12.10) with ESMTP id i97FnObc007336 for ; Thu, 7 Oct 2004 11:49:24 -0400 Received: from localhost.redhat.com (porkchop.devel.redhat.com [172.16.58.2]) by int-mx1.corp.redhat.com (8.11.6/8.11.6) with ESMTP id i97FnIr27404; Thu, 7 Oct 2004 11:49:18 -0400 Received: from gnu.org (localhost [127.0.0.1]) by localhost.redhat.com (Postfix) with ESMTP id 5B19228D2; Thu, 7 Oct 2004 11:48:59 -0400 (EDT) Message-ID: <4165656B.4070007@gnu.org> Date: Thu, 07 Oct 2004 16:16:00 -0000 From: Andrew Cagney User-Agent: Mozilla/5.0 (X11; U; NetBSD macppc; en-GB; rv:1.4.1) Gecko/20040831 MIME-Version: 1.0 To: Joel Brobecker , Dave Korn , "'Eli Zaretskii'" Cc: gdb@sources.redhat.com Subject: Re: Discussion: Formalizing the deprecation process in GDB References: <20041007024047.GB1282@gnat.com> <20041007144852.GG1282@gnat.com> In-Reply-To: <20041007144852.GG1282@gnat.com> Content-Type: text/plain; charset=us-ascii; format=flowed Content-Transfer-Encoding: 7bit X-SW-Source: 2004-10/txt/msg00219.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). Yea, bad example :-) "observer.texi" illustrates a [contraversial?] compromise, at least the documentation is in a single place. (BTW, JeffJ pointed out to me that the observer.texi doco has a bug - it doesn't document how to add a new observer - knowing to modify observer.texi isn't "obvious" :-). "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. 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 :-). Andrew