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

[Eli Zaretskii <eliz@gnu.org>]

How about the text below?

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?


 @item whatis [@var{arg}]
 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 members.  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}}.
 [...]
 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
 are always preserved by @code{ptype}.