From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4630 invoked by alias); 18 Mar 2014 07:47:40 -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 4620 invoked by uid 89); 18 Mar 2014 07:47:39 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-0.4 required=5.0 tests=AWL,BAYES_20,SPF_PASS,T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 X-HELO: bastet.se.axis.com Received: from bastet.se.axis.com (HELO bastet.se.axis.com) (195.60.68.11) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Tue, 18 Mar 2014 07:47:37 +0000 Received: from localhost (localhost [127.0.0.1]) by bastet.se.axis.com (Postfix) with ESMTP id ABBA8180B1 for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from bastet.se.axis.com ([IPv6:::ffff:127.0.0.1]) by localhost (bastet.se.axis.com [::ffff:127.0.0.1]) (amavisd-new, port 10024) with LMTP id oWs82-2QqyoB for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from boulder.se.axis.com (boulder.se.axis.com [10.0.2.104]) by bastet.se.axis.com (Postfix) with ESMTP id 303441809B for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from boulder.se.axis.com (localhost [127.0.0.1]) by postfix.imss71 (Postfix) with ESMTP id 19A5AC04 for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from seth.se.axis.com (seth.se.axis.com [10.0.2.172]) by boulder.se.axis.com (Postfix) with ESMTP id 0EB5E70A for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from xmail2.se.axis.com (xmail2.se.axis.com [10.0.5.74]) by seth.se.axis.com (Postfix) with ESMTP id 0CCD33E048 for ; Tue, 18 Mar 2014 08:47:34 +0100 (CET) Received: from lnxricardw1.se.axis.com (10.88.7.2) by xmail2.se.axis.com (10.0.5.74) with Microsoft SMTP Server (TLS) id 8.3.342.0; Tue, 18 Mar 2014 08:47:33 +0100 Date: Tue, 18 Mar 2014 07:47:00 -0000 From: Ricard Wanderlof To: "gdb-patches@sourceware.org" Subject: Re: [RFC] Stop putting function comments in foo.h In-Reply-To: <53276F7C.7000105@earthlink.net> Message-ID: References: <53271DC0.3050405@redhat.com> <53276F7C.7000105@earthlink.net> User-Agent: Alpine 2.02 (DEB 1266 2009-07-14) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8"; format=flowed Content-Transfer-Encoding: 8BIT X-SW-Source: 2014-03/txt/msg00409.txt.bz2 >>> 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 solution would be to simply duplicate the documentation in both the .c and .h files. Sure, it's duplicated text, and there's always the possibility that they'll get out of sync with each other, but at least we're putting the burdon on whoever is writing the code, not whoever is reading it, which makes sense since the code will be read many more times than it is (re)written. /Ricard -- Ricard Wolf Wanderlöf ricardw(at)axis.com Axis Communications AB, Lund, Sweden www.axis.com Phone +46 46 272 2016 Fax +46 46 13 61 30