From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3824 invoked by alias); 13 Jun 2009 11:48:46 -0000 Received: (qmail 3815 invoked by uid 22791); 13 Jun 2009 11:48:45 -0000 X-SWARE-Spam-Status: No, hits=-2.4 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; Sat, 13 Jun 2009 11:48:38 +0000 Received: (qmail 26387 invoked from network); 13 Jun 2009 11:48:36 -0000 Received: from unknown (HELO orlando.local) (pedro@127.0.0.2) by mail.codesourcery.com with ESMTPA; 13 Jun 2009 11:48:36 -0000 From: Pedro Alves To: Eli Zaretskii Subject: Re: [commit] cleanup stale exec.{h|c} xfer_memory comments. Date: Sat, 13 Jun 2009 11:48:00 -0000 User-Agent: KMail/1.9.10 Cc: gdb-patches@sourceware.org References: <200906121943.08246.pedro@codesourcery.com> In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200906131250.02973.pedro@codesourcery.com> 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: 2009-06/txt/msg00353.txt.bz2 On Saturday 13 June 2009 04:47:05, Eli Zaretskii wrote: > > From: Pedro Alves > > Date: Fri, 12 Jun 2009 19:43:07 +0100 > > > > The comment describing section_table_xfer_memory_partial is actually > > still describing the old xfer_memory. This removes that stale > > description, and adjusts the description in the header a bit better > > to current reality. > > Is the convention to describe functions in headers? I don't believe there's a convention here. Some modules describe exported functions in the .c file, others in the .h file, others in both. E.g., just looking around, I see gdbthread.h, inferior.h, serial.h, charset.h, dwarf2-frame.h, describing functions in the headers. The other exported functions of exec.c were described in the header (and the ones that are new came from target.h, that describes many function in the header too, including the ones related to section_table_xfer_memory_partial). I thought I'd follow suit for consistency with the surrounding code. > That's reasonable > for data structures, but we have a lot of functions documented right > before their source, not in the headers. I find the documentation in > the .c files easier to use, because you don't need to consult another > file. Fine with me. But if we're going to move the description of this function, we should move all the others in exec.h too. Shall I do this, or do you want to do it? > This is C, not C++, so the interface and the implementation are > not separated. I must not understand header files then. (I've no idea why C++ is being referenced here.) -- Pedro Alves