From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30491 invoked by alias); 23 Dec 2011 15:12:44 -0000 Received: (qmail 30480 invoked by uid 22791); 23 Dec 2011 15:12:42 -0000 X-SWARE-Spam-Status: No, hits=-1.0 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout21.012.net.il (HELO mtaout21.012.net.il) (80.179.55.169) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 23 Dec 2011 15:12:29 +0000 Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0LWN00J00WTVBM00@a-mtaout21.012.net.il> for gdb-patches@sourceware.org; Fri, 23 Dec 2011 17:12:25 +0200 (IST) Received: from HOME-C4E4A596F7 ([84.229.233.41]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LWN00JS2WWOBB10@a-mtaout21.012.net.il>; Fri, 23 Dec 2011 17:12:25 +0200 (IST) Date: Fri, 23 Dec 2011 16:01:00 -0000 From: Eli Zaretskii Subject: Re: FYI: minsyms documentation In-reply-to: <4EF39E85.3050207@earthlink.net> To: Stan Shebs Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83vcp7xqxx.fsf@gnu.org> References: <4EF38DAD.3040106@earthlink.net> <8362h8z60x.fsf@gnu.org> <4EF39E85.3050207@earthlink.net> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-12/txt/msg00810.txt.bz2 > Date: Thu, 22 Dec 2011 13:17:57 -0800 > From: Stan Shebs > > On 12/22/11 12:49 PM, Eli Zaretskii wrote: > >> From: Tom Tromey > >> Cc: gdb-patches@sourceware.org > >> Date: Thu, 22 Dec 2011 13:13:19 -0700 > >> > >> My working assumption is that gdbint.texinfo is barely maintained at > >> all. > > Only because none of the active developers want to document GDB > > internals in a Texinfo manual. Therefore, the sad state of > > gdbint.texinfo is a testament of what the majority of GDB maintainers > > think it should look like. > > > > Perhaps that means we should rethink whether we need gdbint.texinfo at > all. That came up as well, you can find the discussions in the archives. > If everybody is able to madly hack away at the code without ever > consulting the internals manual, then what purpose is it serving > exactly? In its current condition, I don't see whom it can serve, except as misinformation. > Are newbies learning by reading the manual, or reading the code? What newbies? The people who hack at the core features of GDB can be counted on fingers of a single hand, and they didn't change in years. > If the latter, then gdbint.texinfo content might get more attention > if it was redistributed into 1-2 page blocks at the tops of relevant > source files. Again, the current content of that manual can only do a mis-service, so redistributing it is wasted effort. If we want to have this kind of material _anywhere_, it must be maintained, i.e. at the very least kept in sync with the development. Documenting complex software in comments is very sub-optimal. It can document each separate API, but it cannot have too much context, and it cannot present the overall design of each feature. It also lacks the means, like hyperlinks, to refer the reader to another place. Linear text performs poorly both as a tutorial introduction and as reference material. You can see all these problems in the proposed minsyms.h, and even in addrmap.h (where clearly the authors went out of their way in providing context: 100+ lines for just 7 APIs!). What we have there is a detailed description of a series of related APIs, but no information about _why_ these APIs are needed, _when_ they should be used, and how they interact with other relevant APIs and with GDB core in general. But I have said this many times in the past, and the result is before your eyes. So I will now crawl back under my rock.