Re: GDB in C++

[Michael Eager <eager@eagercon.com>]

Thiago Jung Bauermann wrote:

> If GDB Internal's contents was transferred to the GDB wiki, maybe people
> would feel more compelled to update and expand it. I know I would try to
> contribute to it as I learn new stuff. The downside when comparing to
> patches against the existing documentation sources would be that peer
> review would be a bit more awkward (but there are ways around it).

The problems with the GDB documentation are not whether it lives
in a .texi file or in a .html file.  The problem is in the content.

The problem is that the GDB docs are, to a large degree, incomplete,
obsolete, unclear, cryptic, and several other adjectives I'll have to
search for in my thesaurus.

While a wiki has some nice features, it would be not closely tied to
any particular GDB version, nor are changes likely to be reviewed for
correctness as would be the case with a patch to the docs in the
source tree.  GDB has been undergoing a number of significant changes
between versions.  The information on a wiki would have no more
likelihood of being accurate than the current docs.

There are two related fixes for this problem.  (Possibly three,
with the first one being recognition that there is a problem.)

1)  The knowledge that the experienced GDB developers have about the
     program needs to be added to the documentation.  This can either be
     by them writing the docs or by them working with a less experienced
     developer who writes the docs.  (You might remember that I offered
     to be the latter a short while ago, but I got no takers.)

2)  The recognition that some of the problems with the documentation
     stem from the fact that GDB is complex, cryptic, unclear and
     convoluted.  There are a number of ways to address this with
     significant refactoring of the code into separate modules with
     well defined interfaces being one, as well as my previous
     suggestion to convert to using real object oriented code instead
     of awkwardly trying to simulate it.


-- 
Michael Eager	 eager@eagercon.com
1960 Park Blvd., Palo Alto, CA 94306  650-325-8077