Re: [doc patch] whatis vs. ptype - the difference

[Jan Kratochvil <jan.kratochvil@redhat.com>]

On Fri, 15 Jul 2011 11:04:51 +0200, Eli Zaretskii wrote:
> How about the text below?

Great; I just have changed there members->methods.

is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}

IMO any "child" of a struct is a member.  Such member can be field, method or
typedef(*).  Therefore the text would either state just "member" or state
"field, method or typedef".  Stating "field or member" seems weird to me.

(*) That is a class typedef, not a subject of ptype unrolling.  class typedef
    is IMO an uncommon construct:
      class C { typedef int t; t i; } c;
    Plus whatis does not unroll one level, that is a bug, going to fix it.


> The only nit that I'm not yet sure about is at the end: "typedefs
> ... at the pointer target".  What do you mean by that? can you show an
> example?

Sorry, thanks for finding it.  So far I had wrong ptype expectation myself,
pointer target typedefs _are_ unrolled by typedef.  Changed the text + extended
the sample code accordingly.

First is included informal wdiff between Eli's text and this one.

The patch with ChangeLog at the bottom is against FSF GDB HEAD.


Thanks,
Jan


------------------------------------------------------------------------------
wdiff against Eli's text:

@@ -13876,7 +13876,7 @@ defined using a @code{typedef}, @code{whatis} will @emph{not} print
the data type underlying the @code{typedef}.  If the type of the
variable or the expression is a compound data type, such as
@code{struct} or  @code{class}, @code{whatis} never prints their
fields or [-members.-]{+methods.+}  It just prints the @code{struct}/@code{class}
name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
such a compound data type, use @code{ptype}.

@@ -13901,9 +13901,10 @@ Contrary to @code{whatis}, @code{ptype} always unrolls any
@code{typedef}s in its argument declaration, whether the argument is
a variable, expression, or a data type.  This means that @code{ptype}
of a variable or an expression will not print literally its type as
present in the source code---use @code{whatis} for that.[-Any-]  @code{typedef}s[-in fields of a @samp{struct} or-] at
the pointer [-target-]{+or reference targets are also unrolled.  Only @code{typedef}s of+}
{+fields, methods and inner @code{class typedef}s of @code{struct}s,+}
{+@code{class}es and @code{union}s+} are [-always preserved by-]{+not unrolled even with+} @code{ptype}.

For example, for this variable declaration:

@@ -13911,7 +13912,8 @@ For example, for this variable declaration:
typedef double real_t;
struct complex @{ real_t real; double imag; @};
typedef struct complex complex_t;
complex_t [-v;-]{+var;+}
{+real_t *real_pointer_var;+}
@end smallexample

@noindent
@@ -13919,9 +13921,9 @@ the two commands give this output:

@smallexample
@group
(@value{GDBP}) whatis [-v-]{+var+}
type = complex_t
(@value{GDBP}) ptype [-v-]{+var+}
type = struct complex @{
    real_t real;
    double imag;
@@ -13935,6 +13937,10 @@ type = struct complex @{
    real_t real;
    double imag;
@}
{+(@value{GDBP}) whatis real_pointer_var+}
{+type = real_t *+}
{+(@value{GDBP}) ptype real_pointer_var+}
{+type = double *+}
@end group
@end smallexample


------------------------------------------------------------------------------
against FSF GDB HEAD:

2011-07-15  Jan Kratochvil  <jan.kratochvil@redhat.com>
	    Eli Zaretskii  <eliz@gnu.org>

	* gdb.texinfo (whatis, ptype): Highlight their differences.  Describe
	typedefs unrolling.  Extend the sample code by an inner typedef and
	outer typedefs unrolling.

--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -13862,16 +13862,34 @@ __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6
 
 @kindex whatis
 @item whatis [@var{arg}]
-Print the data type of @var{arg}, which can be either an expression or
-a data type.  With no argument, print the data type of @code{$}, the
-last value in the value history.  If @var{arg} is an expression, it is
-not actually evaluated, and any side-effecting operations (such as
-assignments or function calls) inside it do not take place.  If
-@var{arg} is a type name, it may be the name of a type or typedef, or
-for C code it may have the form @samp{class @var{class-name}},
-@samp{struct @var{struct-tag}}, @samp{union @var{union-tag}} or
-@samp{enum @var{enum-tag}}.
-@xref{Expressions, ,Expressions}.
+Print the data type of @var{arg}, which can be either an expression
+or a name of a data type.  With no argument, print the data type of
+@code{$}, the last value in the value history.
+
+If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it
+is not actually evaluated, and any side-effecting operations (such as
+assignments or function calls) inside it do not take place.
+
+If @var{arg} is a variable or an expression, @code{whatis} prints its
+literal type as it is used in the source code.  If the type was
+defined using a @code{typedef}, @code{whatis} will @emph{not} print
+the data type underlying the @code{typedef}.  If the type of the
+variable or the expression is a compound data type, such as
+@code{struct} or  @code{class}, @code{whatis} never prints their
+fields or methods.  It just prints the @code{struct}/@code{class}
+name (a.k.a.@: its @dfn{tag}).  If you want to see the members of
+such a compound data type, use @code{ptype}.
+
+If @var{arg} is a type name that was defined using @code{typedef},
+@code{whatis} @dfn{unrolls} only one level of that @code{typedef}.
+Unrolling means that @code{whatis} will show the underlying type used
+in the @code{typedef} declaration of @var{arg}.  However, if that
+underlying type is also a @code{typedef}, @code{whatis} will not
+unroll it.
+
+For C code, the type names may also have the form @samp{class
+@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union
+@var{union-tag}} or @samp{enum @var{enum-tag}}.
 
 @kindex ptype
 @item ptype [@var{arg}]
@@ -13879,10 +13897,23 @@ for C code it may have the form @samp{class @var{class-name}},
 detailed description of the type, instead of just the name of the type.
 @xref{Expressions, ,Expressions}.
 
+Contrary to @code{whatis}, @code{ptype} always unrolls any
+@code{typedef}s in its argument declaration, whether the argument is
+a variable, expression, or a data type.  This means that @code{ptype}
+of a variable or an expression will not print literally its type as
+present in the source code---use @code{whatis} for that.  @code{typedef}s at
+the pointer or reference targets are also unrolled.  Only @code{typedef}s of
+fields, methods and inner @code{class typedef}s of @code{struct}s,
+@code{class}es and @code{union}s are not unrolled even with @code{ptype}.
+
 For example, for this variable declaration:
 
 @smallexample
-struct complex @{double real; double imag;@} v;
+typedef double real_t;
+struct complex @{ real_t real; double imag; @};
+typedef struct complex complex_t;
+complex_t var;
+real_t *real_pointer_var;
 @end smallexample
 
 @noindent
@@ -13890,13 +13921,26 @@ the two commands give this output:
 
 @smallexample
 @group
-(@value{GDBP}) whatis v
+(@value{GDBP}) whatis var
+type = complex_t
+(@value{GDBP}) ptype var
+type = struct complex @{
+    real_t real;
+    double imag;
+@}
+(@value{GDBP}) whatis complex_t
+type = struct complex
+(@value{GDBP}) whatis struct complex
 type = struct complex
-(@value{GDBP}) ptype v
+(@value{GDBP}) ptype struct complex
 type = struct complex @{
-    double real;
+    real_t real;
     double imag;
 @}
+(@value{GDBP}) whatis real_pointer_var
+type = real_t *
+(@value{GDBP}) ptype real_pointer_var
+type = double *
 @end group
 @end smallexample