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

Jan Kratochvil
2010-08-31T13:02:29Z

On Mon, 30 Aug 2010 20:38:06 +0200, Tom Tromey wrote:
> >>>>> "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.

This is definitely a disagreement. Such general guide should be in
doc/gdbint.texinfo .

> 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.

Implementation should name the field in the interface to be able to jump
there.

> That said, my general rule for hacking on gdb is to just follow whatever
> style is in use wherever I am hacking.

I also do so but I still find it wrong.

Thanks,
Jan