From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 2746 invoked by alias); 3 Jan 2012 02:53:21 -0000 Received: (qmail 2738 invoked by uid 22791); 3 Jan 2012 02:53:20 -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; Tue, 03 Jan 2012 02:53:06 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 1B6852BB05A; Mon, 2 Jan 2012 21:53:06 -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 V52qYXVoD5NP; Mon, 2 Jan 2012 21:53:06 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id 86BF82BB059; Mon, 2 Jan 2012 21:53:05 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 5E943145615; Tue, 3 Jan 2012 06:52:56 +0400 (RET) Date: Tue, 03 Jan 2012 02:53:00 -0000 From: Joel Brobecker To: Tom Tromey Cc: Stan Shebs , gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation Message-ID: <20120103025256.GD2730@adacore.com> References: <4EF38DAD.3040106@earthlink.net> <20111223042053.GW23376@adacore.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: 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: 2012-01/txt/msg00071.txt.bz2 > Joel> So, perhaps the right approach lies in the middle. Only apply > Joel> Tom's approach to parts where it should in fact be an API. > > I think one question worth asking is -- what parts of GDB would *not* be > an API? > > I think the answer is, or should be, "none". I would be OK with that. It has the nice property of being simple. It's similar to me wanting every function to have a description comment, no matter how useless the comment might appear. That way, we don't have to try to guess whether documentation is needed or not. > I don't see much point in attempting anything like this if the general > opinion of the other maintainers is against it. I haven't seen enough > replies to consider that there is a consensus, but I will hew to > whatever it is. I don't have a strong opinion. I think there are pluses and minuses to both approaches, so it's not a clear decision. We just have to make a decision. For myself, I have a slight preference for your suggestion, so count me in. It is worth mentioning the fact that, when I first started hacking on GDB, I was appalled at the fact that you could not read a .h file and get both the API and the associated documentation. To me, it was incomprehensible that someone would chose to document, and bury, an API in the .c file. But I also quickly found that this approach allows you to quickly find the documentation, so I got used to it and kinda grew to like it. One of the issues this was supposed to solve, I was told, is that you can have the same function declared in multiple .h files, which is a big "ugh", but true I guess. We could follow Ada's example, where compilation units have specs and bodies. The filename is the same both , except that the .ads extension (spec, equivalent of .h in C/C++) gets replaced by the .adb extension (body, .c/.cc in C/C++). No more ada-tasks.c functions documented in ada-lang.h. One of my regular fustrations is trying to figure out where functions declared in values.h or symtab.h are implemented... GNAT's coding style goes a little further, and requires that all functions have a declaration before a definition. This is another debate that we had, with some people liking them, while others found them to be a maintenance liability. The thing about this style is that it allows us to have a declaration for every function, and to document the functions there, presumably at the start of the unit body. Despite the extra maintenance burden, this has some advantages as well. But I think it only works well in practice because there is a compiler switch to enforce that policy - no function definition without a declaration first. -- Joel