From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17896 invoked by alias); 26 Jun 2007 18:36:14 -0000 Received: (qmail 17887 invoked by uid 22791); 26 Jun 2007 18:36:13 -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 18:36:11 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id F152C2A9C4E; Tue, 26 Jun 2007 14:36:09 -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 J8CpeoGNYMhE; Tue, 26 Jun 2007 14:36:09 -0400 (EDT) Received: from [127.0.0.1] (nile.gnat.com [205.232.38.5]) by rock.gnat.com (Postfix) with ESMTP id A3ABD2A9C4F; Tue, 26 Jun 2007 14:36:09 -0400 (EDT) Message-ID: <46815C98.5080208@adacore.com> Date: Tue, 26 Jun 2007 18:36:00 -0000 From: Robert Dewar User-Agent: Thunderbird 1.5.0.12 (Windows/20070509) MIME-Version: 1.0 To: Markus Deuling CC: Eli Zaretskii , pkoning@equallogic.com, jimb@codesourcery.com, eager@eagercon.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> <46815BC2.9070204@de.ibm.com> In-Reply-To: <46815BC2.9070204@de.ibm.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/msg00313.txt.bz2 Markus Deuling wrote: > Eli Zaretskii wrote: > >> 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. >> > > Maybe the process of getting a patch into mainline should be changed. Currently a patch without a proper > Changelog has no chance. Maybe we should extend that and say a patch must have Changelog and one or two > lines (or even moren) in documentation whenever reasonable. It's a very important principle that stuff in the changelog is *not* a substitute for proper documentation in the source. That's a common mistake (I catch it all the time in the GNAT sources, where all checkins get reviewed by me with this in mind :-)) > > For example the guy that wrote the part for inferior function calls definitely wrote no doc :-) > > For my opinion GDB's Internal Manual is very important and should be cultivated much more. >