From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 1724 invoked by alias); 22 Dec 2011 04:44:45 -0000 Received: (qmail 1716 invoked by uid 22791); 22 Dec 2011 04:44:44 -0000 X-SWARE-Spam-Status: No, hits=-2.0 required=5.0 tests=AWL,BAYES_00 X-Spam-Check-By: sourceware.org Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 22 Dec 2011 04:44:25 +0000 Received: from localhost (localhost.localdomain [127.0.0.1]) by filtered-rock.gnat.com (Postfix) with ESMTP id 5446B2BAB0A; Wed, 21 Dec 2011 23:44:24 -0500 (EST) Received: from rock.gnat.com ([127.0.0.1]) by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) with LMTP id pgdfU8A2wyb4; Wed, 21 Dec 2011 23:44:24 -0500 (EST) Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) by rock.gnat.com (Postfix) with ESMTP id E0D752BAF29; Wed, 21 Dec 2011 23:44:23 -0500 (EST) Received: by joel.gnat.com (Postfix, from userid 1000) id 8F2E8145615; Wed, 21 Dec 2011 20:44:16 -0800 (PST) Date: Thu, 22 Dec 2011 05:17:00 -0000 From: Joel Brobecker To: Tom Tromey Cc: gdb-patches@sourceware.org Subject: Re: FYI: minsyms documentation Message-ID: <20111222044416.GN23376@adacore.com> References: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.20 (2009-06-14) 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: 2011-12/txt/msg00760.txt.bz2 > Today I decided to try to document the minsyms API more or less the way > I would like APIs to be documented in general. This patch implements > that; it move documentation from function definitions to minsyms.h, adds > an introductory comment about minsyms there as well, and it rearranges > the header into a more logical order. OK. Let's move in that direction. I think it makes sense, the API should tell the developer how it expects to be used. Keeping the "See header" comment is important too, IMO, makes it easier to verify that a given function is in fact documeted or not. -- Joel