This is the mail archive of the
gdb@sources.redhat.com
mailing list for the GDB project.
Re: Discussion: Formalizing the deprecation process in GDB
- From: Joel Brobecker <brobecker at gnat dot com>
- To: Eli Zaretskii <eliz at gnu dot org>
- Cc: Andrew Cagney <cagney at gnu dot org>, gdb at sources dot redhat dot com
- Date: Wed, 6 Oct 2004 19:40:48 -0700
- Subject: Re: Discussion: Formalizing the deprecation process in GDB
- References: <20040927175539.GS974@gnat.com> <41637DBD.8030209@gnu.org> <01c4aba7$Blat.v2.2.2$141c3ea0@zahav.net.il>
> Unfortunately, it doesn't help in making a progress in this
> discussion, since all it does is reiterate your opinions that were
> clear (at least to me) during the XM_FILE debate, or else explaining
> principles and generalities that don't need to be explained.
The reason why I sent my message was that I felt that both parties
had exposed their views and that both had their merits. So I felt
that it was necessary to bring more people in the discussion and
decide one way or the other. I suggested that the discussion group
be the global maintainers for instance.
> I'm not sure what is it that you are saying here. Should we abandon
> gdbint.texinfo and instead rely on the code to explain itself, because
> ``we are programmers and thus code is the only thing we read''? Maybe
> I should stop trying so hard to review each documentation patch in a
> matter of days, because the code already says all there is to tell?
Just my two cents on this specific topic:
I do agree with Andrew that the place were developers search
for documentation is the code. I would love to see a lot of the
documentation contained in gdbint.texinfo be moved as comments
into the code. Having the documentation embedded inside the code
is very convenient, and also where I have been trained to look
first.
This does not mean that I am suggesting that we get rid of gdbint
entirely. I see chapters and sections that can only be placed in
a separate documentation, such as how to add support for a new
host for instance. But the documentation about partial symbol
tables, for instance, would be much more useful directly in
symtab.h or symtab.c.
I don't know about others, but I have read the gdbint manual once
from cover to cover almost 4 years ago, and never refered to it
anymore.
--
Joel