From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13076 invoked by alias); 24 Sep 2007 19:12:17 -0000 Received: (qmail 13064 invoked by uid 22791); 24 Sep 2007 19:12:17 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 24 Sep 2007 19:12:14 +0000 Received: (qmail 20202 invoked from network); 24 Sep 2007 19:12:12 -0000 Received: from unknown (HELO localhost) (jimb@127.0.0.2) by mail.codesourcery.com with ESMTPA; 24 Sep 2007 19:12:12 -0000 To: Thiago Jung Bauermann Cc: GDB Patches Subject: Re: [patch] describe some frame unwinder functions References: <1190584664.8479.2.camel@localhost.localdomain> From: Jim Blandy Date: Mon, 24 Sep 2007 19:12:00 -0000 In-Reply-To: <1190584664.8479.2.camel@localhost.localdomain> (Thiago Jung Bauermann's message of "Sun, 23 Sep 2007 18:57:44 -0300") Message-ID: User-Agent: Gnus/5.11 (Gnus v5.11) Emacs/22.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii 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: 2007-09/txt/msg00344.txt.bz2 Thiago Jung Bauermann writes: > This patch adds explanations to some functions in the frame unwinder. I > think they're very helpful (albeit somewhat concise), assuming I got > them right. :-) These functions all have comments where they're declared in frame.h. I think it would be best to fix those if they're not clear; I don't think we should repeat function head comments in both places. There seem to be two schools regarding comments. One says to put them in header files, becase a module's .h file is its interface, and that's where people should go to see how to use it. The other says to put them directly above the functions, because that's where the actual code is. GDB sort of does both, or neither, depending on the age and original author of the code. The Subversion project's coding standard followed the header file approach, with the requirement that the comments had to be good enough to use the functions without reading their code, in most cases. Where that standard is in force, I think header files are the right place. For example, prologue-value.h, macrotab.h, and macroexp.h all work fine this way. For some parts of GDB, the real-life behaviors of the functions themselves are hairy enough that it may be unrealistic to ever expect anyone to use them without reading their code.