From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14572 invoked by alias); 23 Jun 2009 20:54:20 -0000 Received: (qmail 14563 invoked by uid 22791); 23 Jun 2009 20:54:19 -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; Tue, 23 Jun 2009 20:54:12 +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 n5NKqA9s027545; Tue, 23 Jun 2009 16:52:10 -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 n5NKq9fq027182; Tue, 23 Jun 2009 16:52:09 -0400 Received: from opsy.redhat.com (vpn-12-196.rdu.redhat.com [10.11.12.196]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id n5NKq8M3001011; Tue, 23 Jun 2009 16:52:09 -0400 Received: by opsy.redhat.com (Postfix, from userid 500) id E6B04888077; Tue, 23 Jun 2009 14:52:07 -0600 (MDT) To: Stan Shebs 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> <4A4133F9.3070208@codesourcery.com> From: Tom Tromey Reply-To: Tom Tromey Date: Tue, 23 Jun 2009 20:54:00 -0000 In-Reply-To: <4A4133F9.3070208@codesourcery.com> (Stan Shebs's message of "Tue\, 23 Jun 2009 12\:58\:49 -0700") 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/msg00638.txt.bz2 >>>>> "Stan" == Stan Shebs writes: Stan> I think that in many cases functions in a header don't get Stan> documentation there because they are intended to be semi-private, and Stan> are only in a header because of the rules of C and our own Stan> conventions. For such functions it would at least be useful to have a Stan> line "semi-private, don't assume you can use this for your own Stan> purposes". Yeah. My ideal in these cases is to have a second header which is private to the implementation. Stan> Should we maybe introduce a coding rule requiring at least a brief Stan> API/usage comment about each function declaration in a header? Perhaps Stan> all the semi-private functions can be separated into a block with a Stan> comment that applies to the lot of them. It would be fine by me, for public APIs. For existing messy headers, I don't care so much (unless someone wants to do some big cleanups on them), but I would like it if new headers were to be written to a Blandyesque standard. Tom