Re: [patch] Code cleanup: Make function typedef for find memory region

[Tom Tromey <tromey@redhat.com>]

>>>>> "Jan" == Jan Kratochvil <jan.kratochvil@redhat.com> writes:

Jan> I am also for requiring comment to be placed at the function
Jan> definition and not at its declaration.  Using tag jumps one will
Jan> never find the declaration and I have considered these functions to
Jan> have no comment (randomly found now
Jan> simple_displaced_step_copy_insn, it was a different function I had
Jan> the problem with).

I think there are three cases.

One case is the "bcache" case: you have a relatively simple data
structure with a defined public API.  In this case, I find it it
convenient to be able to read the header file to see the entire exported
API, without being distracted by the implementation.  This case is maybe
not as typical as we might like; many data types in gdb are semi-opaque
at best.

The second case is implementations of virtual methods.  Here, the
comment belongs at the point of definition.  I think commenting the
method implementation is actually (mildly) bad, because it means copying
documentation, with the problems that implies.

The last case is the rest of gdb -- semi-opaque data structures, utility
functions, etc.  For these I think using the definition is preferable.

That said, my general rule for hacking on gdb is to just follow whatever
style is in use wherever I am hacking.  If I were writing new code, I
might aspire to the bcache approach; but otherwise I just comment the
definition.

Jan> I am also for forbidding putting comments there at both places as
Jan> such way they get inconsistent soon or they differ etc. (randomly
Jan> found init_type).

I agree.

Tom