From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 6438 invoked by alias); 22 Dec 2011 20:13:48 -0000 Received: (qmail 6428 invoked by uid 22791); 22 Dec 2011 20:13:46 -0000 X-SWARE-Spam-Status: No, hits=-8.2 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,RP_MATCHES_RCVD,SPF_HELO_PASS X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 22 Dec 2011 20:13:22 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id pBMKDKh9024600 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 22 Dec 2011 15:13:21 -0500 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id pBMKDKVs013963; Thu, 22 Dec 2011 15:13:20 -0500 Received: from barimba (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id pBMKDJ3L031823; Thu, 22 Dec 2011 15:13:19 -0500 From: Tom Tromey To: Stan Shebs Cc: gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation References: <4EF38DAD.3040106@earthlink.net> Date: Thu, 22 Dec 2011 20:21:00 -0000 In-Reply-To: <4EF38DAD.3040106@earthlink.net> (Stan Shebs's message of "Thu, 22 Dec 2011 12:06:05 -0800") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2011-12/txt/msg00795.txt.bz2 >>>>> "Stan" == Stan Shebs writes: Stan> On 12/21/11 6:34 PM, Tom Tromey wrote: >> I am checking this in on the trunk. >> >> Today I decided to try to document the minsyms API more or less the way >> I would like APIs to be documented in general. This patch implements >> that; it move documentation from function definitions to minsyms.h, adds >> an introductory comment about minsyms there as well, and it rearranges >> the header into a more logical order. Stan> I'm not liking this idea very much I'm afraid. Ok. Do you mean you want me to back out the patch? Let me know. Stan> Second, this is potentially a very large change to the sources, but if Stan> it's incremental, then we get into a confusing situation where some Stan> files are changed, others are not, and some headers are half-changed Stan> because they service multiple source files. This is the present situation. Tom> My view is that gdbint.texinfo should eventually hold a high-level Tom> overview of the different modules in GDB, but that each individual Tom> module should be documented in the relevant header files. My reason for Tom> this is just that it is simpler to update documentation when it is in Tom> the form of comments. I think gdbint.texinfo should also hold Tom> documentation on our procedures, coding styles, and other things that Tom> are not directly related to some piece of code. Stan> Isn't that generally our working assumption now? My working assumption is that gdbint.texinfo is barely maintained at all. Tom