Re: FYI: minsyms documentation

[Joel Brobecker <brobecker@adacore.com>]

> I'm not liking this idea very much I'm afraid.

I don't have a strong opinion on this. I think you made some
good comments on the downside of this approach. But I also
think it does have some advantages as well.

I do think that...

> Doxygen output tends to make functions look more self-contained and
> well-defined than would actually be the case for most of GDB.

... is a weakness of our design, which makes it harder to use
as justification for another decision.

For me, I came to enjoy the fact that function descriptions can
always be found by locating the function implementation, which
in most cases is unique, and can be found using grep. But I also
recognize that many a times I have searched through the routines
applying to a given "object" searching for something that might
do what I want to do. Not having the documentation right next
to it was a real productivity hit.

So, perhaps the right approach lies in the middle. Only apply
Tom's approach to parts where it should in fact be an API. Things
like gdb_usleep, or vec.h are obvious candidates, for instance.
You've got to love how addrmap.h is documented, making it much
easier to use that module. And in the same vein, the "object"-like
structures that have use in GDB (symbols, symbol tables, values,
etc) could be documented similarly.

I should also mention this: One approach, followed by GNAT
engineers, is that they always have a declaration, either
in the package spec (header) or at the beginning of the package
body (.c file). And they always provide the function description
where the declaration is made. Should a function become public,
they move the whole blob, declaration and documentation to the
spec. I am not a fan, but if people like it, we can experiment
with that idea.

One thing I would like, though, is for all of us to insist on
every new function being documented. Even some GMs do not follow
or enforce this rule...

-- 
Joel