From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9507 invoked by alias); 6 Mar 2007 20:40:08 -0000 Received: (qmail 9498 invoked by uid 22791); 6 Mar 2007 20:40:07 -0000 X-Spam-Check-By: sourceware.org Received: from mx2.palmsource.com (HELO mx2.palmsource.com) (12.7.175.14) by sourceware.org (qpsmtpd/0.31) with ESMTP; Tue, 06 Mar 2007 20:40:03 +0000 Received: from localhost (localhost [127.0.0.1]) by localhost.domain.tld (Postfix) with ESMTP id 3977213568E; Tue, 6 Mar 2007 12:40:02 -0800 (PST) Received: from mx2.palmsource.com ([127.0.0.1]) by localhost (mx2.palmsource.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 14359-05-7; Tue, 6 Mar 2007 12:40:01 -0800 (PST) Received: from ussunex01.palmsource.com (unknown [192.168.101.9]) by mx2.palmsource.com (Postfix) with ESMTP id 1A3AA1355B8; Tue, 6 Mar 2007 12:40:01 -0800 (PST) Received: from 192.168.92.81 ([192.168.92.81]) by ussunex01.palmsource.com ([192.168.101.9]) via Exchange Front-End Server owa.palmsource.com ([10.0.20.17]) with Microsoft Exchange Server HTTP-DAV ; Tue, 6 Mar 2007 20:40:00 +0000 Received: from svmsnyderlnx by owa.palmsource.com; 06 Mar 2007 12:39:59 -0800 Subject: Re: [Patch]: Little Cleanup From: Michael Snyder To: Joel Brobecker Cc: Eli Zaretskii , Jim Blandy , mark.kettenis@xs4all.nl, deuling@de.ibm.com, pedro_alves@portugalmail.pt, gdb-patches@sourceware.org In-Reply-To: <20070306195211.GA18974@adacore.com> References: <45E7CC17.5040304@de.ibm.com> <45E93AE5.5050704@portugalmail.pt> <45EBB15E.4000602@de.ibm.com> <200703052119.l25LJKVw021917@brahms.sibelius.xs4all.nl> <20070306195211.GA18974@adacore.com> Content-Type: text/plain Content-Transfer-Encoding: 7bit Date: Tue, 06 Mar 2007 20:40:00 -0000 Message-Id: <1173213599.29183.103.camel@localhost.localdomain> Mime-Version: 1.0 X-Mailer: Evolution 2.4.1 X-IsSubscribed: yes 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: 2007-03/txt/msg00060.txt.bz2 On Tue, 2007-03-06 at 11:52 -0800, Joel Brobecker wrote: > > > The place to document the meaning of a function's return value is at > > > the function, not at each of its call sites. > > > > So you are saying that it's normal to expect the code reader to > > constantly jump to the function's definition trying to understand what > > its callers try to accomplish? > > Then perhaps this suggests that the function could be renamed into > something clearer? But otherwise, yes, I agree with Jim and Mark, > because maintaining these comments everywhere is going to be an issue. Yes. The logical place for a function to be documented is at the definition -- not at the call.