Re: [patch] describe some frame unwinder functions

[Jim Blandy <jimb at codesourcery dot com>]

Thiago Jung Bauermann <bauerman@br.ibm.com> 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.