Re: Discussion: Formalizing the deprecation process in GDB

["Eli Zaretskii" <eliz at gnu dot org>]

> Date: Wed, 6 Oct 2004 19:40:48 -0700
> From: Joel Brobecker <brobecker@gnat.com>
> Cc: Andrew Cagney <cagney@gnu.org>, gdb@sources.redhat.com
> 
> 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.

The problem with having documentation in the code is that there's no
easy way of organizing such a documentation: no cross-references, no
chapter/section/subsection structure, and no index.  For someone who
is on the learning curve looking for a more-or-less complete
description of a specific GDB mechanism, let alone a high-level
architectural overview, these disadvantages are IMO significant and
grave.

In addition, code comments in many cases have a loophole view of the
code, and so higher-level aspects tend to be not documented at all.
Code comments are also not reviewed as formally as docs submissions
are.

As an illustration to these deficiencies, please see how many
questions we have on this mailing list asking to explain how some
specific GDB feature works, and how they are almost _never_ answered
by pointing people to the code comments, nor to the docs.  Does anyone
need a better demonstration of the fact that our code is largely
undocumented?

If we are willing to move in the direction of making the docs and the
code closer (and assuming volunteers will step forward to do the job),
we could look at the various systems that generate code and manuals
from the same source.  Failing that, I'd rather support having _more_
of the explanations in the manual and less in the comments, and adding
references in the comments to relevant gdbint.texinfo places.  I think
that on balance this is a better alternative than the opposite one,
where we prefer comments to Texinfo docs.

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

That is simply because of the poor quality (in terms of coverage of
the relevant subject matter) of gdbint.texinfo.  We should do much
better.