Re: FYI: minsyms documentation

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 22 Dec 2011 13:17:57 -0800
> From: Stan Shebs <stanshebs@earthlink.net>
> 
> On 12/22/11 12:49 PM, Eli Zaretskii wrote:
> >> From: Tom Tromey<tromey@redhat.com>
> >> Cc: gdb-patches@sourceware.org
> >> Date: Thu, 22 Dec 2011 13:13:19 -0700
> >>
> >> My working assumption is that gdbint.texinfo is barely maintained at
> >> all.
> > Only because none of the active developers want to document GDB
> > internals in a Texinfo manual.  Therefore, the sad state of
> > gdbint.texinfo is a testament of what the majority of GDB maintainers
> > think it should look like.
> >
> 
> Perhaps that means we should rethink whether we need gdbint.texinfo at 
> all.

That came up as well, you can find the discussions in the archives.

> If everybody is able to madly hack away at the code without ever 
> consulting the internals manual, then what purpose is it serving 
> exactly?

In its current condition, I don't see whom it can serve, except as
misinformation.

> Are newbies learning by reading the manual, or reading the code?

What newbies?  The people who hack at the core features of GDB can be
counted on fingers of a single hand, and they didn't change in years.

> If the latter, then gdbint.texinfo content might get more attention
> if it was redistributed into 1-2 page blocks at the tops of relevant
> source files.

Again, the current content of that manual can only do a mis-service,
so redistributing it is wasted effort.  If we want to have this kind
of material _anywhere_, it must be maintained, i.e. at the very least
kept in sync with the development.

Documenting complex software in comments is very sub-optimal.  It can
document each separate API, but it cannot have too much context, and
it cannot present the overall design of each feature.  It also lacks
the means, like hyperlinks, to refer the reader to another place.
Linear text performs poorly both as a tutorial introduction and as
reference material.

You can see all these problems in the proposed minsyms.h, and even in
addrmap.h (where clearly the authors went out of their way in
providing context: 100+ lines for just 7 APIs!).  What we have there
is a detailed description of a series of related APIs, but no
information about _why_ these APIs are needed, _when_ they should be
used, and how they interact with other relevant APIs and with GDB core
in general.

But I have said this many times in the past, and the result is before
your eyes.  So I will now crawl back under my rock.