From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10540 invoked by alias); 16 Mar 2014 09:51:13 -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 10525 invoked by uid 89); 16 Mar 2014 09:51:12 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.3 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS autolearn=ham version=3.3.2 X-HELO: moutng.kundenserver.de Received: from moutng.kundenserver.de (HELO moutng.kundenserver.de) (212.227.17.13) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Sun, 16 Mar 2014 09:51:11 +0000 Received: from smtp.ascolab.com ([213.95.4.182]) by mrelayeu.kundenserver.de (node=mreue105) with ESMTP (Nemesis) id 0Lk9Jy-1X1Dgv23y6-00cAu6; Sun, 16 Mar 2014 10:51:07 +0100 Received: from localhost (localhost [127.0.0.1]) by smtp.ascolab.com (Postfix) with ESMTP id 49107E0B28 for ; Sun, 16 Mar 2014 10:51:06 +0100 (CET) Received: from smtp.ascolab.com ([127.0.0.1]) by localhost (smtp.ascolab.com [127.0.0.1]) (amavisd-new, port 10026) with LMTP id j9WmQ_sBhB39 for ; Sun, 16 Mar 2014 10:51:04 +0100 (CET) Received: from lt-gergap.localnet (p3E9C2FC8.dip0.t-ipconnect.de [62.156.47.200]) by smtp.ascolab.com (Postfix) with ESMTPSA id 50E2FE0B26 for ; Sun, 16 Mar 2014 10:51:04 +0100 (CET) From: Gerhard Gappmeier To: gdb-patches@sourceware.org Subject: Re: [RFC] Stop putting function comments in foo.h Date: Sun, 16 Mar 2014 09:51:00 -0000 Message-ID: <1934010.kCBWkLNBL4@lt-gergap> User-Agent: KMail/4.12 (Linux/3.12.6-gentoo; KDE/4.12.0; x86_64; ; ) In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" X-IsSubscribed: yes X-SW-Source: 2014-03/txt/msg00349.txt.bz2 On Saturday, March 15, 2014 12:45:41 PM Doug Evans wrote: > Hi. > > 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? > > 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. It's not just you ;-) Hi had this discussion several times inside my company. IMO the only valid reason for having the doxygen comments in the header file is when you are doing binary distributions with header files and libraries. This is not the case for Open Source. If code is distributed it makes more sense to have the comments in the source file. Here you need the comments as developer when debugging through the code, changing it, or just reviewing it. It annoys me to switch to the header file to see what a function is doing. Another advantage of doing so is that the header file stays clean if you want to get a quick overview of what functions are available. But that's my opinion and I'm sure other people will have other opinions ;-)