From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20390 invoked by alias); 27 Jun 2007 00:42:19 -0000 Received: (qmail 20379 invoked by uid 22791); 27 Jun 2007 00:42:18 -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; Wed, 27 Jun 2007 00:42:16 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id D4CE72A9C63; Tue, 26 Jun 2007 20:42:14 -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 4isfHIT4xcmh; Tue, 26 Jun 2007 20:42:14 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id AD0C92A9C3B; Tue, 26 Jun 2007 20:42:14 -0400 (EDT) Message-ID: <4681B264.2090709@adacore.com> Date: Wed, 27 Jun 2007 00:42:00 -0000 From: Robert Dewar User-Agent: Thunderbird 1.5.0.12 (Windows/20070509) MIME-Version: 1.0 To: Jim Blandy CC: Joel Brobecker , 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> <4681A48E.8060201@adacore.com> In-Reply-To: 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/msg00330.txt.bz2 Jim Blandy wrote: > Robert Dewar writes: >> 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. > > You're right; this doesn't make sense as written. > > I write the comments in the code before I write the code, because I've > found that the effort of trying to explain what I'm about to try to do > helps clarify my own understanding a great deal. For me, at least, it > makes enough of a difference that I'm sure I come out ahead, if you > include debugging time. I find the same thing, and even more these days, I find I can't rely on my memory so well, so if I come back to code I wrote 6 months ago, I need the documentation as much as anyone :-) > > In other words, if the internals documentation is written before the > code, then, for me, it is a worthwhile investment. In that case, I do > believe that writing that documentation brings the completion date > closer, and I write it. I don't know whether other contributors need > this particular crutch; I'm pretty sure some don't. > > The only other time I write explanations is when someone asks for > help; here, again, the investment is worthwhile, because someone is > about to go off and write some code, and I can bring their completion > date closer. Most of what I've contributed to gdbint.texinfo got in > there because Eli liked something I'd written on the mailing list and > asked me to put it there. certainly fair enough. One thing that I have found helpful is to ask newcomers to report as bugs cases in which the code is not clear, and then when the explanations are given, or the detective work completed, help write the documentation they found missing.