From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 22493 invoked by alias); 30 Aug 2010 15:04:16 -0000 Received: (qmail 22361 invoked by uid 22791); 30 Aug 2010 15:04:14 -0000 X-SWARE-Spam-Status: No, hits=-6.0 required=5.0 tests=AWL,BAYES_00,RCVD_IN_DNSWL_HI,SPF_HELO_PASS,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 30 Aug 2010 15:04:10 +0000 Received: from int-mx02.intmail.prod.int.phx2.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o7UF3sBp029512 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Mon, 30 Aug 2010 11:03:54 -0400 Received: from host1.dyn.jankratochvil.net (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx02.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o7UF3q6t016981 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 30 Aug 2010 11:03:54 -0400 Received: from host1.dyn.jankratochvil.net (localhost [127.0.0.1]) by host1.dyn.jankratochvil.net (8.14.4/8.14.4) with ESMTP id o7UF3qNo004011; Mon, 30 Aug 2010 17:03:52 +0200 Received: (from jkratoch@localhost) by host1.dyn.jankratochvil.net (8.14.4/8.14.4/Submit) id o7UF3pt4004010; Mon, 30 Aug 2010 17:03:51 +0200 Date: Mon, 30 Aug 2010 15:04:00 -0000 From: Jan Kratochvil To: Joel Brobecker Cc: gdb-patches@sourceware.org Subject: Re: [patch] Code cleanup: Make function typedef for find memory region Message-ID: <20100830150351.GA3837@host1.dyn.jankratochvil.net> References: <20100830085953.GA25961@host1.dyn.jankratochvil.net> <20100830141454.GG2986@adacore.com> <20100830142507.GA1356@host1.dyn.jankratochvil.net> <20100830145815.GH2986@adacore.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20100830145815.GH2986@adacore.com> User-Agent: Mutt/1.5.20 (2009-12-10) 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: 2010-08/txt/msg00519.txt.bz2 On Mon, 30 Aug 2010 16:58:15 +0200, Joel Brobecker wrote: > > I am also for requiring comment to be placed at the function definition and > > not at its declaration. Using tag jumps one will never find the declaration > > and I have considered these functions to have no comment (randomly found now > > simple_displaced_step_copy_insn, it was a different function I had the problem > > with). > > That has been my approach as well, so I'm not the one that needs > convincing. However, proponents of comments with the definition ^^^^^^^^^^->declaration [ The mail would not make sense otherwise. ] > also have a good point. When you have a nice public API declared > in a .h file, it's convenient to have the documentation there. > I still think that it's better to be consistent in the location > of the documentation, particularly if the names we choose in the API > are clear enough that it gives us a general idea of what each entity > is about. We can then read the comment of the functions of interest. Yes, I understand the reasons of the "wrong" placement but IMHO it is not worth the pain, one can very easily jump forth and back while reading it. Thanks, Jan