From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19116 invoked by alias); 22 Dec 2011 21:06:48 -0000 Received: (qmail 19098 invoked by uid 22791); 22 Dec 2011 21:06:44 -0000 X-SWARE-Spam-Status: No, hits=-3.6 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE,RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from elasmtp-spurfowl.atl.sa.earthlink.net (HELO elasmtp-spurfowl.atl.sa.earthlink.net) (209.86.89.66) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 22 Dec 2011 21:06:31 +0000 Received: from [70.170.59.51] (helo=macbook2.local) by elasmtp-spurfowl.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1RdpqR-0004Ej-85 for gdb-patches@sourceware.org; Thu, 22 Dec 2011 16:06:31 -0500 Message-ID: <4EF39BD6.8080802@earthlink.net> Date: Thu, 22 Dec 2011 21:18:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:8.0) Gecko/20111105 Thunderbird/8.0 MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation References: <4EF38DAD.3040106@earthlink.net> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da940d801409a4108581a3cc96139aa8a42a0350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes 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/msg00798.txt.bz2 On 12/22/11 12:13 PM, Tom Tromey wrote: >>>>>> "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. We don't need to be that hasty. :-) I'd like to see more thoughts and reactions; if everybody else likes it, I won't stand in the way of progress! > > 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. True, and certainly we should provide some sort of guidance on the point. One way to look at it is if we assume that the transition to C++ occurs at some point, what happens to current function head comments? Do they tend to stay put, as explanation of a method's implementation, or do they tend to migrate to class definitions in headers? Perhaps method implementations won't often need head comment blocks at all, as the interface is documented in headers, and anything interesting in the implementation is described with inline comments as is is now. Stan