From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9324 invoked by alias); 25 Jun 2007 20:31:42 -0000 Received: (qmail 9315 invoked by uid 22791); 25 Jun 2007 20:31:42 -0000 X-Spam-Check-By: sourceware.org Received: from romy.inter.net.il (HELO romy.inter.net.il) (213.8.233.24) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 25 Jun 2007 20:31:38 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-162-148.inter.net.il [80.230.162.148]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id IED20611 (AUTH halo1); Mon, 25 Jun 2007 23:31:19 +0300 (IDT) Date: Mon, 25 Jun 2007 20:31:00 -0000 Message-Id: From: Eli Zaretskii To: Robert Dewar CC: pkoning@equallogic.com, jimb@codesourcery.com, eager@eagercon.com, stanshebs@earthlink.net, gdb@sources.redhat.com In-reply-to: <4680199F.7020906@adacore.com> (message from Robert Dewar on Mon, 25 Jun 2007 15:38:07 -0400) Subject: Re: What's an annex? stratum? Reply-to: Eli Zaretskii 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> 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/msg00265.txt.bz2 > Date: Mon, 25 Jun 2007 15:38:07 -0400 > From: Robert Dewar > > 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. > > I disagree, properly arranged comments in the code can most > certainly serve as internals documentation Code comments lack good provisions for such important aspects of documentation as cross-references, indices, and hierarchical structure. Without these, all comments can present is an unstructured collection of unrelated notes. > I am opposed to having separate internals documentation, I think it > is much better to have this in the source files. That's not surprising: programmers don't like writing documentation as much as they like writing code. That is one reason why gdbint.texinfo is in such poor shape. In any case, if people here believe comments are a reasonable substitute for documentation, perhaps I should from now on reject code patches that do not explain themselves clearly, and do not contain enough references to other related portions of GDB.