From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22257 invoked by alias); 26 Jun 2007 23:43:17 -0000 Received: (qmail 22248 invoked by uid 22791); 26 Jun 2007 23:43:16 -0000 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.31) with ESMTP; Tue, 26 Jun 2007 23:43:14 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 9CA5E2A9AA4; Tue, 26 Jun 2007 19:43:12 -0400 (EDT) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 5I3U+EEjVydT; Tue, 26 Jun 2007 19:43:12 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id 6E2832A9A82; Tue, 26 Jun 2007 19:43:12 -0400 (EDT) Message-ID: <4681A48E.8060201@adacore.com> Date: Tue, 26 Jun 2007 23:43:00 -0000 From: Robert Dewar User-Agent: Thunderbird 1.5.0.12 (Windows/20070509) MIME-Version: 1.0 To: Joel Brobecker CC: Jim Blandy , Markus Deuling , Eli Zaretskii , pkoning@equallogic.com, eager@eagercon.com, stanshebs@earthlink.net, gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <468009EA.4040504@eagercon.com> <18048.5444.903092.843811@pkoning.equallogic.com> <20070625193135.GA6391@caradoc.them.org> <4680199F.7020906@adacore.com> <46815BC2.9070204@de.ibm.com> <4681A073.5040209@adacore.com> <20070626234056.GZ3706@adacore.com> In-Reply-To: <20070626234056.GZ3706@adacore.com> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-IsSubscribed: yes Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org X-SW-Source: 2007-06/txt/msg00325.txt.bz2 Joel Brobecker wrote: > I think you misunderstood what Jim was saying. Jim documents his code > very well, and gives examples of that. What he says is that it's a lot > easier to maintain doco besides the associated code itself rather than > maintain a separate document (which is pretty much what you argued for). > Given the amount of resources that we have, this is probably the most > pragmatic approach to keeping our code documented. By all means I agree that it is better to have documentation as part of the source files. Of course the effort of *producing* the initial documentation is pretty much independent of whether the documentation is in the source files or in separate files, so when I read: > Time spent on the internals documentation has, itself, no effect on > users' experience with GDB. It's only worthwhile if that time, plus > the time then spent doing something users *will* notice, is less than > the time needed just to do something user-visible without internals > documentation. It is hard to read into this a viewpoint that says that time spent on the internals documentation is OK if it is in the source files, but not if it is in separate files. I still read the above quoted para as questioning the value of internals documentation, and to me such documentation is an essential part of any complex piece of software. But certainly I apologize to Jim if I misunderand his position.