From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9309 invoked by alias); 23 Jun 2009 19:59:09 -0000 Received: (qmail 9297 invoked by uid 22791); 23 Jun 2009 19:59:08 -0000 X-SWARE-Spam-Status: No, hits=-2.3 required=5.0 tests=AWL,BAYES_00,SPF_PASS X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 23 Jun 2009 19:58:57 +0000 Received: (qmail 1545 invoked from network); 23 Jun 2009 19:58:55 -0000 Received: from unknown (HELO macbook-2.local) (stan@127.0.0.2) by mail.codesourcery.com with ESMTPA; 23 Jun 2009 19:58:55 -0000 Message-ID: <4A4133F9.3070208@codesourcery.com> Date: Tue, 23 Jun 2009 19:59:00 -0000 From: Stan Shebs User-Agent: Thunderbird 2.0.0.21 (Macintosh/20090302) MIME-Version: 1.0 To: tromey@redhat.com CC: 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> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit 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/msg00634.txt.bz2 Tom Tromey wrote: >>>>>> "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. > I think that in many cases functions in a header don't get documentation there because they are intended to be semi-private, and are only in a header because of the rules of C and our own conventions. For such functions it would at least be useful to have a line "semi-private, don't assume you can use this for your own purposes". Should we maybe introduce a coding rule requiring at least a brief API/usage comment about each function declaration in a header? Perhaps all the semi-private functions can be separated into a block with a comment that applies to the lot of them. Stan