This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: FYI: minsyms documentation
- From: Joel Brobecker <brobecker at adacore dot com>
- To: Tom Tromey <tromey at redhat dot com>
- Cc: Stan Shebs <stanshebs at earthlink dot net>, gdb-patches at sourceware dot org
- Date: Tue, 3 Jan 2012 06:52:56 +0400
- Subject: Re: FYI: minsyms documentation
- References: <m3vcp972sf.fsf@fleche.redhat.com> <4EF38DAD.3040106@earthlink.net> <20111223042053.GW23376@adacore.com> <m3fwfxhhvp.fsf@fleche.redhat.com>
> Joel> So, perhaps the right approach lies in the middle. Only apply
> Joel> Tom's approach to parts where it should in fact be an API.
>
> I think one question worth asking is -- what parts of GDB would *not* be
> an API?
>
> I think the answer is, or should be, "none".
I would be OK with that. It has the nice property of being simple.
It's similar to me wanting every function to have a description
comment, no matter how useless the comment might appear. That way,
we don't have to try to guess whether documentation is needed or
not.
> I don't see much point in attempting anything like this if the general
> opinion of the other maintainers is against it. I haven't seen enough
> replies to consider that there is a consensus, but I will hew to
> whatever it is.
I don't have a strong opinion. I think there are pluses and minuses
to both approaches, so it's not a clear decision. We just have to
make a decision. For myself, I have a slight preference for your
suggestion, so count me in.
It is worth mentioning the fact that, when I first started hacking
on GDB, I was appalled at the fact that you could not read a .h file
and get both the API and the associated documentation. To me, it was
incomprehensible that someone would chose to document, and bury,
an API in the .c file. But I also quickly found that this approach
allows you to quickly find the documentation, so I got used to it
and kinda grew to like it.
One of the issues this was supposed to solve, I was told, is that
you can have the same function declared in multiple .h files, which
is a big "ugh", but true I guess. We could follow Ada's example,
where compilation units have specs and bodies. The filename is
the same both , except that the .ads extension (spec, equivalent
of .h in C/C++) gets replaced by the .adb extension (body, .c/.cc
in C/C++). No more ada-tasks.c functions documented in ada-lang.h.
One of my regular fustrations is trying to figure out where functions
declared in values.h or symtab.h are implemented...
GNAT's coding style goes a little further, and requires that all
functions have a declaration before a definition. This is another
debate that we had, with some people liking them, while others
found them to be a maintenance liability. The thing about this
style is that it allows us to have a declaration for every function,
and to document the functions there, presumably at the start of
the unit body. Despite the extra maintenance burden, this has some
advantages as well. But I think it only works well in practice
because there is a compiler switch to enforce that policy - no
function definition without a declaration first.
--
Joel