From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 16744 invoked by alias); 17 Mar 2014 16:09:24 -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 16735 invoked by uid 89); 17 Mar 2014 16:09:23 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-1.8 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: mx1.redhat.com Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 17 Mar 2014 16:09:23 +0000 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s2HG9JjH029574 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 17 Mar 2014 12:09:19 -0400 Received: from [127.0.0.1] (ovpn01.gateway.prod.ext.ams2.redhat.com [10.39.146.11]) by int-mx10.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id s2HG7S9J001207; Mon, 17 Mar 2014 12:07:29 -0400 Message-ID: <53271DC0.3050405@redhat.com> Date: Mon, 17 Mar 2014 16:09:00 -0000 From: Pedro Alves User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130625 Thunderbird/17.0.7 MIME-Version: 1.0 To: Doug Evans CC: gdb-patches Subject: Re: [RFC] Stop putting function comments in foo.h References: In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-SW-Source: 2014-03/txt/msg00376.txt.bz2 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? 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 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. :-) -- Pedro Alves