From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31593 invoked by alias); 25 Jun 2007 20:09:43 -0000 Received: (qmail 31581 invoked by uid 22791); 25 Jun 2007 20:09:42 -0000 X-Spam-Check-By: sourceware.org Received: from shell4.bayarea.net (HELO shell4.bayarea.net) (209.128.82.1) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 25 Jun 2007 20:09:40 +0000 Received: (qmail 28482 invoked from network); 25 Jun 2007 13:09:38 -0700 Received: from 209-128-106-254.bayarea.net (HELO ?192.168.20.7?) (209.128.106.254) by shell4.bayarea.net with SMTP; 25 Jun 2007 13:09:38 -0700 Message-ID: <46802100.6050600@eagercon.com> Date: Mon, 25 Jun 2007 20:09:00 -0000 From: Michael Eager User-Agent: Thunderbird 1.5.0.9 (X11/20070102) MIME-Version: 1.0 To: Paul Koning CC: dewar@adacore.com, jimb@codesourcery.com, stanshebs@earthlink.net, gdb@sources.redhat.com Subject: Re: What's an annex? stratum? References: <467D5FEF.7010900@eagercon.com> <467D6D1F.7090507@earthlink.net> <467D6FB8.4080909@eagercon.com> <468009EA.4040504@eagercon.com> <18048.5444.903092.843811@pkoning.equallogic.com> <20070625193135.GA6391@caradoc.them.org> <4680199F.7020906@adacore.com> <18048.7178.168032.6683@pkoning.equallogic.com> In-Reply-To: <18048.7178.168032.6683@pkoning.equallogic.com> Content-Type: text/plain; charset=UTF-8; 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/msg00261.txt.bz2 Paul Koning wrote: >>>>>> "Robert" == Robert Dewar writes: > > Robert> On Mon, Jun 25, 2007 at 03:19:32PM -0400, Paul Koning wrote: > >> That's really unfortunate. Comments in code are useful but they > >> are no substitute for properly written internals documentation. > > Robert> I disagree, properly arranged comments in the code can most > Robert> certainly serve as internals documentation, and have a FAR > Robert> better chance of being kept up to date. I am opposed to > Robert> having separate internals documentation, I think it is much > Robert> better to have this in the source files. > > Usual practice is for source comments to be local explanation, not > global explanation. Documentation provides context which is not often available in source comments. The source comments are valuable, but you have to know where to start or the context in which the comments are appropriate. (For example, my questions about annex and stratum are not answered in the source.) Internals documentation provides a guide through the program in some kind of logical order. It's difficult to provide that order at the file or function scope. > But in any case, if internals documentation existed in the sources, > I'd be a happy camper. Me too. -- Michael Eager eager@eagercon.com 1960 Park Blvd., Palo Alto, CA 94306 650-325-8077