From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10211 invoked by alias); 15 Jan 2012 18:01:33 -0000 Received: (qmail 10177 invoked by uid 22791); 15 Jan 2012 18:01:31 -0000 X-SWARE-Spam-Status: No, hits=-1.8 required=5.0 tests=AWL,BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_NONE X-Spam-Check-By: sourceware.org Received: from caibbdcaaaaf.dreamhost.com (HELO homiemail-a48.g.dreamhost.com) (208.113.200.5) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sun, 15 Jan 2012 18:01:18 +0000 Received: from homiemail-a48.g.dreamhost.com (localhost [127.0.0.1]) by homiemail-a48.g.dreamhost.com (Postfix) with ESMTP id 0D9B44F8058; Sun, 15 Jan 2012 10:01:18 -0800 (PST) Received: from redwood.eagercon.com (c-76-102-3-160.hsd1.ca.comcast.net [76.102.3.160]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: eager@eagerm.com) by homiemail-a48.g.dreamhost.com (Postfix) with ESMTPSA id DD2AF4F8057; Sun, 15 Jan 2012 10:01:17 -0800 (PST) Message-ID: <4F13146D.9040301@eagerm.com> Date: Sun, 15 Jan 2012 18:49:00 -0000 From: Michael Eager User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:8.0) Gecko/20111115 Thunderbird/8.0 MIME-Version: 1.0 To: gdb-patches@sourceware.org, Joel Brobecker , Stan Shebs , Tom Tromey Subject: Re: FYI: minsyms documentation References: In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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: 2012-01/txt/msg00522.txt.bz2 On 12/21/2011 06: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. I realize that I'm late to this discussion, but I dislike this approach and think that it will make maintaining GDB more difficult and makes using and maintaining the documentation more difficult. It requires looking in two places, the .c and the .h at the same time. When I'm debugging something, the .c is in the debugger window and if there are any useful comments I see them. This change requires me to open the .h in a different editor window and search for the function name. Most of the time I'm not going to do this, since almost all the time, the comments don't say very much. This means that when there is a comment which might explain what to me is an unexpected behavior, I'm likely to see it only much later, if at all, when it occurs to me that there might be something in the .h file which is relevant. Best practice, comments are best kept close to the code that they refer to. Maintainers are likely to update comments if they are next to the modified code, and much less likely if the comments are somewhere else. It doesn't matter if that somewhere else is in a .h file, or in the .texi files, or in some other area. There are actually decades of experimental evidence in favor of keeping detailed comments close to the relevant code, rather than removing them to a different location. It would be nice to see GDB documentation improve and documenting the APIs would be great. I see this as providing high level concept documentation which explains how a particular API works, why it exists, and how it interacts with other APIs. Minimal documentation of each function, without context, is not this. As far as I can tell, there minsyms.h contains one very short paragraph which provides a bit of context and there is no general overview. To use an analogy, this is like giving you the description of a spark plug, a fuel pump, and a crankshaft, and expecting you to figure out how these interact to make a car engine turn. -- Michael Eager eager@eagercon.com 1960 Park Blvd., Palo Alto, CA 94306 650-325-8077