Re: RFA: "maint print type" should print all the flag bits

[Stan Shebs <shebs at apple dot com>]

Jim Blandy wrote:
> 
> Eli Zaretskii <eliz@is.elta.co.il> writes:
> > > They're only meant for use by GDB developers.
> >
> > How do you expect the GDB developers to discover their existence if
> > they aren't documented?  Even if they do discover their existence, how
> > would a developer who never used a particular command know what it
> > does?  The built-in doc strings are terse and don't explain much.  For
> > example, suppose i use "maint print type" and see it print
> > TYPE_FLAG_TARGET_STUB--how do I figure out what that means?  (If you
> > think that GDB's sources explain that clearly, think again ;-)
> >
> > I think every command should be documented in the manual.
> 
> Well, you're right, of course.  There's no good reason *not* to
> document them, other than laziness.

I'll mention again a script that I had Jason write one time (that's
probably lost to posterity), which was to collect all the
commands in the sources, and all the commands documented in the
manual, and diff the two.  Very handy, because it shows commands
that are not documented, and encourages both manual and source to
be written in a fashion that makes it easy for the script to find
them.

(And yes, the followup suggestion will be to generate both source
and doc from a single file, but that's a big project.  The comparison
script would only take an hour or two to get to the point of bein
useful.)

On the location of maint command docs, I don't think it matters
much whether it is in appendix or regular chapter.  Readers will
be smart enough to realize that they don't need to use the commands
unless a GDB maintainer asks them to run one.

Stan