From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21771 invoked by alias); 23 Dec 2011 04:21:20 -0000 Received: (qmail 21756 invoked by uid 22791); 23 Dec 2011 04:21:16 -0000 X-SWARE-Spam-Status: No, hits=-2.0 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Fri, 23 Dec 2011 04:21:03 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 413932BB021; Thu, 22 Dec 2011 23:21:02 -0500 (EST) 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 J1HEI2xv8oQA; Thu, 22 Dec 2011 23:21:02 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id C3B732BB017; Thu, 22 Dec 2011 23:21:01 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id D3A95145615; Thu, 22 Dec 2011 20:20:53 -0800 (PST) Date: Fri, 23 Dec 2011 10:38:00 -0000 From: Joel Brobecker To: Stan Shebs Cc: gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation Message-ID: <20111223042053.GW23376@adacore.com> References: <4EF38DAD.3040106@earthlink.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <4EF38DAD.3040106@earthlink.net> User-Agent: Mutt/1.5.20 (2009-06-14) 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/msg00800.txt.bz2 > I'm not liking this idea very much I'm afraid. I don't have a strong opinion on this. I think you made some good comments on the downside of this approach. But I also think it does have some advantages as well. I do think that... > Doxygen output tends to make functions look more self-contained and > well-defined than would actually be the case for most of GDB. ... is a weakness of our design, which makes it harder to use as justification for another decision. For me, I came to enjoy the fact that function descriptions can always be found by locating the function implementation, which in most cases is unique, and can be found using grep. But I also recognize that many a times I have searched through the routines applying to a given "object" searching for something that might do what I want to do. Not having the documentation right next to it was a real productivity hit. So, perhaps the right approach lies in the middle. Only apply Tom's approach to parts where it should in fact be an API. Things like gdb_usleep, or vec.h are obvious candidates, for instance. You've got to love how addrmap.h is documented, making it much easier to use that module. And in the same vein, the "object"-like structures that have use in GDB (symbols, symbol tables, values, etc) could be documented similarly. I should also mention this: One approach, followed by GNAT engineers, is that they always have a declaration, either in the package spec (header) or at the beginning of the package body (.c file). And they always provide the function description where the declaration is made. Should a function become public, they move the whole blob, declaration and documentation to the spec. I am not a fan, but if people like it, we can experiment with that idea. One thing I would like, though, is for all of us to insist on every new function being documented. Even some GMs do not follow or enforce this rule... -- Joel