From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19476 invoked by alias); 6 Aug 2009 18:42:36 -0000 Received: (qmail 19467 invoked by uid 22791); 6 Aug 2009 18:42:36 -0000 X-SWARE-Spam-Status: No, hits=-2.4 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from smtp-outbound-2.vmware.com (HELO smtp-outbound-2.vmware.com) (65.115.85.73) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 06 Aug 2009 18:42:30 +0000 Received: from mailhost3.vmware.com (mailhost3.vmware.com [10.16.27.45]) by smtp-outbound-2.vmware.com (Postfix) with ESMTP id 1738E9; Thu, 6 Aug 2009 11:42:29 -0700 (PDT) Received: from [10.20.94.141] (msnyder-server.eng.vmware.com [10.20.94.141]) by mailhost3.vmware.com (Postfix) with ESMTP id 0E1E3CD905; Thu, 6 Aug 2009 11:42:29 -0700 (PDT) Message-ID: <4A7B23CE.4060801@vmware.com> Date: Thu, 06 Aug 2009 19:12:00 -0000 From: Michael Snyder User-Agent: Thunderbird 1.5.0.12 (X11/20080411) MIME-Version: 1.0 To: Eli Zaretskii CC: Tom Tromey , "uweigand@de.ibm.com" , "thiago.bauermann@gmail.com" , "gdb-patches@sourceware.org" , "pedro@codesourcery.com" , "jkratoch@redhat.com" Subject: Re: [rfc] Infrastructure to disable breakpoints during inferior startup References: <200908051814.n75IED4s005139@d12av02.megacenter.de.ibm.com> <833a84olra.fsf@gnu.org> In-Reply-To: <833a84olra.fsf@gnu.org> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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: 2009-08/txt/msg00092.txt.bz2 Eli Zaretskii wrote: >> Cc: eliz@gnu.org, thiago.bauermann@gmail.com (Thiago Jung Bauermann), >> gdb-patches@sourceware.org, pedro@codesourcery.com, >> jkratoch@redhat.com >> From: Tom Tromey >> Date: Thu, 06 Aug 2009 09:58:54 -0600 >> >> I think there is still a need for an internals document, because there >> are things worth documenting that don't have a natural location in a >> source file. I'm thinking of things like coding conventions, HIG >> guidelines for new commands, etc -- things that affect future decisions >> but that are not inherent in the code. > > That's one reason for the internals manual. The other -- which IMO is > a more important one (but I'm in minority here) -- is that Texinfo > allows you to organize the documentation for easy reading in ways code > comments never will. You cannot have index entries in comments, and > you cannot have cross-references which are easy to be followed, two > features without which reading about a complicated topic described in > several places is a PITA. > > So ideally, we should have both code comments and corresponding manual > docs, IMO. I'm with Eli, FWIW. We need both. We'll never document everything in the internals manual, but the more the better.