From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17243 invoked by alias); 15 Jun 2009 18:31:58 -0000 Received: (qmail 17195 invoked by uid 22791); 15 Jun 2009 18:31:58 -0000 X-SWARE-Spam-Status: No, hits=-2.3 required=5.0 tests=AWL,BAYES_00,SPF_HELO_PASS,SPF_PASS X-Spam-Check-By: sourceware.org Received: from mx2.redhat.com (HELO mx2.redhat.com) (66.187.237.31) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 15 Jun 2009 18:31:49 +0000 Received: from int-mx2.corp.redhat.com (int-mx2.corp.redhat.com [172.16.27.26]) by mx2.redhat.com (8.13.8/8.13.8) with ESMTP id n5FITNP4020445; Mon, 15 Jun 2009 14:29:23 -0400 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx2.corp.redhat.com (8.13.1/8.13.1) with ESMTP id n5FITMmo004227; Mon, 15 Jun 2009 14:29:22 -0400 Received: from opsy.redhat.com (vpn-13-64.rdu.redhat.com [10.11.13.64]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id n5FITLJw021716; Mon, 15 Jun 2009 14:29:21 -0400 Received: by opsy.redhat.com (Postfix, from userid 500) id 726583784BE; Mon, 15 Jun 2009 12:29:20 -0600 (MDT) To: Joel Brobecker Cc: Eli Zaretskii , Pedro Alves , gdb-patches@sourceware.org Subject: Re: [commit] cleanup stale exec.{h|c} xfer_memory comments. References: <200906121943.08246.pedro@codesourcery.com> <20090613111210.GN25703@adacore.com> From: Tom Tromey Reply-To: tromey@redhat.com Date: Mon, 15 Jun 2009 18:31:00 -0000 In-Reply-To: <20090613111210.GN25703@adacore.com> (Joel Brobecker's message of "Sat\, 13 Jun 2009 07\:12\:10 -0400") Message-ID: User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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: 2009-06/txt/msg00397.txt.bz2 >>>>> "Joel" == Joel Brobecker writes: Joel> Unfortunately, I don't think we really have a hard convention in GDB. Joel> For C, I also tend to prefer documenting the function next to the Joel> implementation. It's the only way to be consistent, since some functions Joel> do not have advance declarations. FWIW, I prefer to have documentation in the header for a module's public API, and next to the implementation for the private API. Consistency doesn't matter as much to me as being able to read a header file and get a grasp of how I would use a module; the private comments in the module can then describe the implementation. There are several examples of this in gdb already. Consider: macro*.[ch], bcache.[ch], dictionary.[ch], addrmap.[ch]. These are all exemplary code, which I think is not coincidental... it requires more work to write the code this way, but that forces one to consciously consider the API. Tom