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

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

On Tue, 12 Jul 2011 22:10:38 +0200, Eli Zaretskii wrote:
> > +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.
> 
> Why is this important?  It doesn't belong to the differences between
> the two commands, AFAIK, does it?

There was not and even after my change there is not any special part of the
text describing the difference.  There is a description of `whatis' and
a description of `ptype'.

I would like a real table there but `info' never shows any real table.
Such as:
       | outer typedefs unrolling           | compound types
----------------------------------------------------------------------
whatis | vars: no unroll, types: one unroll | displayed only type name
ptype  | all unrolled                       | displayed both name and its fields

GDB is missing the ultimate command which would do always the right thing:
dream  | vars: no unroll, types: one unroll | displayed both name and its fields
 - but that is outside of the scope of this doc-only patch.


> >                                      @code{whatis} prints the type of
> > +@var{arg} as used in the source code
> 
> The "as used in the source code" part is confusing.  What exactly does
> it mean, and how, if at all, is that different from ptype?

whatis v -> complex_t
ptype v -> struct complex

The source code uses type `complex_t' type for the variable `v'.


> >                                       possibly including any typedefs.
> 
> "Possibly"?  You mean it sometimes does and sometimes does not?  If
> so, when does it?

"including any possible typedefs" may be right?

That is, if there are any typedefs they are included.  But sure there exist
variables having nothing to do with typedefs (`long x;').


> > +@code{whatis} never prints fields of compound types like @samp{struct}s.
> 
> This part is clear.
> 
> > +@code{whatis} unrolls in such case only one layer of outer typedef at a time.
> 
> This sounds incorrect, because your example says:
> 
> > +complex_t v;
> >  [...]
> >  (@value{GDBP}) whatis v
> > +type = complex_t
> 
> That is, there's no "unrolling" here, not even of a single layer.
> Unless I misunderstood what you mean by "unrolling", that is.

This "unrolls [...] only one layer" is in the paragraph "If @var{arg} is
a type name".  As `v' is a variable the paragraph "If @var{arg} is an
expression" applies instead (where no typedefs unrolling is stated).


> > +Any inner typedefs --- such as fields of @samp{struct} or typedefs at the
> > +pointer target --- are always preserved by both @code{whatis} and @code{ptype}.
> 
> Not clear what that means.  whatis doesn't show struct members at all,
> does it?  If so, how can it "preserve" those fields?

That's true, my mistake, this should be removed from the `whatis' description.


> > +@code{ptype} always unrolls all outer typedefs contrary to @code{whatis}.
> 
> Instead of talking about "unrolling", wouldn't it be better to say
> that ptype recursively looks up the definition of each type until it
> arrives at primitive data types, and prints the result only then?

I would like to avoid "recursive" and keep more at the Frank Eigler's "unroll"
term to state that the first non-typedefs stops the "unrolling".  I found it
is a common confusion when explaining this difference that people think ptype
will display "double real" (and not "real_t real" as it displays).


> > +@code{ptype} of an expression (variable) will not print its real type including
> > +possible typedefs as present in the source code
> 
> Not clear.  The "real" part is getting in the way.  Don't you mean
> "literal", not "real"?

Maybe "literal".  I want to express the major defect of `ptype' - that `ptype v'
does not show `complex_t' anywhere.


> > +Any inner typedefs --- such as fields of @samp{struct} or typedefs at
> > +the pointer target --- are always preserved by both @code{whatis} and
> > +@code{ptype}.
> 
> Not clear: what are "inner typedefs"?  If a struct has a member that
> is itself a struct, what will ptype show about this member?

I have demonstrated the behavior on the `real' field in the sample code.
Inside `struct[' - the `inner typedefs' - are never touched by `ptype'.


> Also, since whatis does not show struct members at all (AFAIU), saying
> "both" here is confusing and misleading, no?

Yes, right.


> I hope answering these questions will allow to rephrase the text so it
> is both accurate and clear.

Depending on your next mail I - or you if you wish - can update the patch.


Thanks,
Jan