Re: FYI: minsyms documentation

[Joel Brobecker <brobecker@adacore.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