Re: [commit] cleanup stale exec.{h|c} xfer_memory comments.

[Pedro Alves <pedro at codesourcery dot com>]

On Saturday 13 June 2009 04:47:05, Eli Zaretskii wrote:
> > From: Pedro Alves <pedro@codesourcery.com>
> > 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