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

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

[Fred Fish]

The "maint print type" command does not print all the flag
bits.  It also should to use the defined macros to test for
the bits.

-Fred

2001-12-09  Fred Fish  <fnf@redhat.com>

	* gdbtypes.c (TYPE_FLAG_UNSIGNED, TYPE_FLAG_STUB): Use
	TYPE_UNSIGNED and TYPE_NOSIGN to determine when to print these
	rather than testing the bits directly.
	(TYPE_FLAG_NOSIGN, TYPE_FLAG_TARGET_STUB, TYPE_FLAG_STATIC,
	TYPE_FLAG_CONST, TYPE_FLAG_VOLATILE, TYPE_FLAG_PROTOTYPED,
	TYPE_FLAG_INCOMPLETE, TYPE_FLAG_CODE_SPACE, TYPE_FLAG_DATA_SPACE,
	TYPE_FLAG_VARARGS): Test for and print these bits as well.

Index: gdbtypes.c
===================================================================
RCS file: /cvs/src/src/gdb/gdbtypes.c,v
retrieving revision 1.29
diff -u -p -r1.29 gdbtypes.c
--- gdbtypes.c	2001/12/07 22:11:51	1.29
+++ gdbtypes.c	2001/12/09 19:08:25
@@ -2846,14 +2844,54 @@ recursive_dump_type (struct type *type, 
   gdb_print_host_address (TYPE_REFERENCE_TYPE (type), gdb_stdout);
   printf_filtered ("\n");
   printfi_filtered (spaces, "flags 0x%x", TYPE_FLAGS (type));
-  if (TYPE_FLAGS (type) & TYPE_FLAG_UNSIGNED)
+  if (TYPE_UNSIGNED (type))
     {
       puts_filtered (" TYPE_FLAG_UNSIGNED");
     }
-  if (TYPE_FLAGS (type) & TYPE_FLAG_STUB)
+  if (TYPE_NOSIGN (type))
     {
+      puts_filtered (" TYPE_FLAG_NOSIGN");
+    }
+  if (TYPE_STUB (type))
+    {
       puts_filtered (" TYPE_FLAG_STUB");
     }
+  if (TYPE_TARGET_STUB (type))
+    {
+      puts_filtered (" TYPE_FLAG_TARGET_STUB");
+    }
+  if (TYPE_STATIC (type))
+    {
+      puts_filtered (" TYPE_FLAG_STATIC");
+    }
+  if (TYPE_CONST (type))
+    {
+      puts_filtered (" TYPE_FLAG_CONST");
+    }
+  if (TYPE_VOLATILE (type))
+    {
+      puts_filtered (" TYPE_FLAG_VOLATILE");
+    }
+  if (TYPE_PROTOTYPED (type))
+    {
+      puts_filtered (" TYPE_FLAG_PROTOTYPED");
+    }
+  if (TYPE_INCOMPLETE (type))
+    {
+      puts_filtered (" TYPE_FLAG_INCOMPLETE");
+    }
+  if (TYPE_CODE_SPACE (type))
+    {
+      puts_filtered (" TYPE_FLAG_CODE_SPACE");
+    }
+  if (TYPE_DATA_SPACE (type))
+    {
+      puts_filtered (" TYPE_FLAG_DATA_SPACE");
+    }
+  if (TYPE_VARARGS (type))
+    {
+      puts_filtered (" TYPE_FLAG_VARARGS");
+    }
   puts_filtered ("\n");
   printfi_filtered (spaces, "nfields %d ", TYPE_NFIELDS (type));
   gdb_print_host_address (TYPE_FIELDS (type), gdb_stdout);

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

[Jim Blandy]

Approved.

Fred Fish <fnf@ns1.ninemoons.com> writes:

> 
> The "maint print type" command does not print all the flag
> bits.  It also should to use the defined macros to test for
> the bits.
> 
> -Fred
> 
> 2001-12-09  Fred Fish  <fnf@redhat.com>
> 
> 	* gdbtypes.c (TYPE_FLAG_UNSIGNED, TYPE_FLAG_STUB): Use
> 	TYPE_UNSIGNED and TYPE_NOSIGN to determine when to print these
> 	rather than testing the bits directly.
> 	(TYPE_FLAG_NOSIGN, TYPE_FLAG_TARGET_STUB, TYPE_FLAG_STATIC,
> 	TYPE_FLAG_CONST, TYPE_FLAG_VOLATILE, TYPE_FLAG_PROTOTYPED,
> 	TYPE_FLAG_INCOMPLETE, TYPE_FLAG_CODE_SPACE, TYPE_FLAG_DATA_SPACE,
> 	TYPE_FLAG_VARARGS): Test for and print these bits as well.
> 
> Index: gdbtypes.c
> ===================================================================
> RCS file: /cvs/src/src/gdb/gdbtypes.c,v
> retrieving revision 1.29
> diff -u -p -r1.29 gdbtypes.c
> --- gdbtypes.c	2001/12/07 22:11:51	1.29
> +++ gdbtypes.c	2001/12/09 19:08:25
> @@ -2846,14 +2844,54 @@ recursive_dump_type (struct type *type, 
>    gdb_print_host_address (TYPE_REFERENCE_TYPE (type), gdb_stdout);
>    printf_filtered ("\n");
>    printfi_filtered (spaces, "flags 0x%x", TYPE_FLAGS (type));
> -  if (TYPE_FLAGS (type) & TYPE_FLAG_UNSIGNED)
> +  if (TYPE_UNSIGNED (type))
>      {
>        puts_filtered (" TYPE_FLAG_UNSIGNED");
>      }
> -  if (TYPE_FLAGS (type) & TYPE_FLAG_STUB)
> +  if (TYPE_NOSIGN (type))
>      {
> +      puts_filtered (" TYPE_FLAG_NOSIGN");
> +    }
> +  if (TYPE_STUB (type))
> +    {
>        puts_filtered (" TYPE_FLAG_STUB");
>      }
> +  if (TYPE_TARGET_STUB (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_TARGET_STUB");
> +    }
> +  if (TYPE_STATIC (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_STATIC");
> +    }
> +  if (TYPE_CONST (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_CONST");
> +    }
> +  if (TYPE_VOLATILE (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_VOLATILE");
> +    }
> +  if (TYPE_PROTOTYPED (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_PROTOTYPED");
> +    }
> +  if (TYPE_INCOMPLETE (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_INCOMPLETE");
> +    }
> +  if (TYPE_CODE_SPACE (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_CODE_SPACE");
> +    }
> +  if (TYPE_DATA_SPACE (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_DATA_SPACE");
> +    }
> +  if (TYPE_VARARGS (type))
> +    {
> +      puts_filtered (" TYPE_FLAG_VARARGS");
> +    }
>    puts_filtered ("\n");
>    printfi_filtered (spaces, "nfields %d ", TYPE_NFIELDS (type));
>    gdb_print_host_address (TYPE_FIELDS (type), gdb_stdout);
> 

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

[Eli Zaretskii]

On Sun, 9 Dec 2001, Fred Fish wrote:

> The "maint print type" command does not print all the flag
> bits.

This command is not documented in the manual.  Could someone please
fill that void?

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

[Jim Blandy]

Eli Zaretskii <eliz@is.elta.co.il> writes:
> On Sun, 9 Dec 2001, Fred Fish wrote:
> > The "maint print type" command does not print all the flag
> > bits.
> 
> This command is not documented in the manual.  Could someone please
> fill that void?

Are the other `maint' commands documented in the manual?  They're only
meant for use by GDB developers.

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

[Eli Zaretskii]

On 10 Dec 2001, Jim Blandy wrote:

> > > The "maint print type" command does not print all the flag
> > > bits.
> > 
> > This command is not documented in the manual.  Could someone please
> > fill that void?
> 
> Are the other `maint' commands documented in the manual?

At least some of them are.  Try "i maint TAB" in Info, and you will
see which ones are there.

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

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

[Eli Zaretskii]

> Date: Tue, 11 Dec 2001 07:40:48 -0800
> From: Michael Snyder <msnyder@redhat.com>
> 
> Perhaps there needs to be a developers manual?

That's a possibility.  However, the number of maint commands is quite
small, and hardly warrants a separate manual.

How about having an Appendix where all maint commands would be
documented?

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

[Andrew Cagney]

> Date: Tue, 11 Dec 2001 07:40:48 -0800
>> From: Michael Snyder <msnyder@redhat.com>
>> 
>> Perhaps there needs to be a developers manual?
> 
> 
> That's a possibility.  However, the number of maint commands is quite
> small, and hardly warrants a separate manual.


I'm about to add another one (``maint print regcache'') :-)


> How about having an Appendix where all maint commands would be
> documented?


That I don't know.

	Andrew

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

[Daniel Jacobowitz]

On Tue, Dec 11, 2001 at 07:20:06PM +0200, Eli Zaretskii wrote:
> > Date: Tue, 11 Dec 2001 07:40:48 -0800
> > From: Michael Snyder <msnyder@redhat.com>
> > 
> > Perhaps there needs to be a developers manual?
> 
> That's a possibility.  However, the number of maint commands is quite
> small, and hardly warrants a separate manual.
> 
> How about having an Appendix where all maint commands would be
> documented?

We have an internals manual, don't we?  The maint commands are only
useful if you're wandering around in the internals.  So why not say as
much in the user manual, and document them in the internals manual?

-- 
Daniel Jacobowitz                           Carnegie Mellon University
MontaVista Software                         Debian GNU/Linux Developer

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

[Andrew Cagney]

> On Tue, Dec 11, 2001 at 07:20:06PM +0200, Eli Zaretskii wrote:
> 
>> > Date: Tue, 11 Dec 2001 07:40:48 -0800
>> > From: Michael Snyder <msnyder@redhat.com>
>> > 
>> > Perhaps there needs to be a developers manual?
> 
>> 
>> That's a possibility.  However, the number of maint commands is quite
>> small, and hardly warrants a separate manual.
>> 
>> How about having an Appendix where all maint commands would be
>> documented?
> 
> 
> We have an internals manual, don't we?  The maint commands are only
> useful if you're wandering around in the internals.  So why not say as
> much in the user manual, and document them in the internals manual?


I think the ``maint'' commands are like the ``remote protocol spec'' and 
the MI interface.  While not for the average user, they do define 
external user accessable interfaces to GDB.

enjoy,
Andrew

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

[Daniel Jacobowitz]

On Tue, Dec 11, 2001 at 05:47:26PM -0800, Andrew Cagney wrote:
> >On Tue, Dec 11, 2001 at 07:20:06PM +0200, Eli Zaretskii wrote:
> >
> >>> Date: Tue, 11 Dec 2001 07:40:48 -0800
> >>> From: Michael Snyder <msnyder@redhat.com>
> >>> 
> >>> Perhaps there needs to be a developers manual?
> >
> >>
> >>That's a possibility.  However, the number of maint commands is quite
> >>small, and hardly warrants a separate manual.
> >>
> >>How about having an Appendix where all maint commands would be
> >>documented?
> >
> >
> >We have an internals manual, don't we?  The maint commands are only
> >useful if you're wandering around in the internals.  So why not say as
> >much in the user manual, and document them in the internals manual?
> 
> 
> I think the ``maint'' commands are like the ``remote protocol spec'' and 
> the MI interface.  While not for the average user, they do define 
> external user accessable interfaces to GDB.

In that case, I'd almost rather rename the Internals manual to a
Developers manual - for development involving, rather than using but
not necessarily directly on, GDB.

I don't consider that fit for the User's manual.

-- 
Daniel Jacobowitz                           Carnegie Mellon University
MontaVista Software                         Debian GNU/Linux Developer

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

[Eli Zaretskii]

On Tue, 11 Dec 2001, Daniel Jacobowitz wrote:

> I don't consider that fit for the User's manual.

I don't see why we should conceal the maint commands from users: what
damage can that possibly cause?

We also shouldn't second-guess what they need: it's perfectly possible
that some maint command could be useful to some user, somewhere.  If
those commands aren't in the user manual, users will never find them.

OTOH, having these commands in the user's manual doesn't present any
disadvantage to the GDB developers.

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

[Eli Zaretskii]

On Tue, 11 Dec 2001, Daniel Jacobowitz wrote:

> The maint commands are only useful if you're wandering around in the
> internals.

I don't necessarily agree, but anyway, it doesn't really matter, IMHO.
What does matter is that someone who wants to find a description of a
command--any command--should know in what manual to look.  Working
with more than a single manual at a time is not very convenient in
most Info readers.

Since the internals manual omits more than it describes, I expect
someone who messes with the internals to read the code more than the
manual.  So having all the commands in one manual is more convenient
even for a GDB developer.

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

[Jim Blandy]

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.

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

[Stan Shebs]

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