From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 23483 invoked by alias); 17 Mar 2014 21:59:33 -0000 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 Received: (qmail 23473 invoked by uid 89); 17 Mar 2014 21:59:32 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.1 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_NONE,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: elasmtp-mealy.atl.sa.earthlink.net Received: from elasmtp-mealy.atl.sa.earthlink.net (HELO elasmtp-mealy.atl.sa.earthlink.net) (209.86.89.69) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 17 Mar 2014 21:59:31 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-mealy.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1WPfW8-0002W7-25 for gdb-patches@sourceware.org; Mon, 17 Mar 2014 17:56:20 -0400 Message-ID: <53276F7C.7000105@earthlink.net> Date: Mon, 17 Mar 2014 21:59:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:24.0) Gecko/20100101 Thunderbird/24.3.0 MIME-Version: 1.0 To: gdb-patches@sourceware.org Subject: Re: [RFC] Stop putting function comments in foo.h References: <53271DC0.3050405@redhat.com> In-Reply-To: <53271DC0.3050405@redhat.com> Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da9402622b21462d8e96e18a2107a86ac6cef350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-IsSubscribed: yes X-SW-Source: 2014-03/txt/msg00399.txt.bz2 On 3/17/14 9:07 AM, Pedro Alves wrote: > On 03/15/2014 07:45 PM, Doug Evans wrote: >> I'd like to start a discussion. >> With doxygen is there still as much value to putting function comments >> in foo.h instead of foo.c? > > IMO, yes. And IMO doxygen here is a red herring. > I actually don't see myself looking at doxygen docs > much. Doxygen is supposed to be an aid, there should be no > requirement to build the doxygen docs to be able to understand > gdb's sources, right? I think that's the right viewpoint. Doxygen normally glues .h and .c comment blocks into a single documentation node, which nicely finesses the whole question of where to record API info, but even so it seems a bit sloppy for us to not make a decision on .h vs .c. > IMO, a module's API documentation should be in its header file, as > that's where the module's "public" contract is defined. > Needing to peek at the module's implementation feels wrong to me. > If the function's documentation isn't clear without looking > at the function's body, something is already wrong with > the comment. I've flip-flopped on this so many times... While it seems most logical to have the API documentation in the .h file, in actual practice the "see foo.h" comments seem awkward and unhelpful. It's matched only by the possibility of having no comment block at all, since many functions in our API have uninteresting bodies. Going the other way has its own issues, for instance only function and variable documentation gets to be in a .c file, structs and enums and macros have to stay in the .h anyway. At the moment I'm leaning to API in .h, and put down the "see" comments as one of the many minor irritations in the C programmer's life. :-) >> I ask because every time I find a "See foo.h." comment I get depressed >> and disappointed. They're just getting in my way, and I'm wondering >> if it's just me. > > Whenever I look at a header file that doesn't document its > functions' interfaces (and often doesn't even list the > parameter names), I get depressed and disappointed. I'm > wondering if it's just me. :-) One of the potential uses for Doxygen is that it has ways to dump raw info about the sources, and we could use that to build things like progress meters - identify the 10 most-used functions that are undocumented and write comments for those, then do the next 10, etc. Right now it's just the large amorphous need, where fixing it feels like trying to empty the ocean with a teaspoon. :-) Stan stan@codesourcery.com