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

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 12 Jul 2011 20:31:30 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> 
> The patch just describes the current behavior.  With my English waiting for
> a doc review.

Thanks.

I must confess that the new description is not much clearer than the
old one.  After reading it (more than once), I still have no clear
idea of the differences between these two commands.  It's obvious that
ptype does a more thorough job that whatis, but what exactly each one
does and does not do is still in the fog for me.

Below I try to ask specific questions in the hope that they will allow
to make this issue more clear.

> +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?

>                                      @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?

>                                       possibly including any typedefs.

"Possibly"?  You mean it sometimes does and sometimes does not?  If
so, when does it?

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

> +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?

Btw, a stylistic point: don't leave whitespace around "---", it looks
ugly in print.

> +@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?

> +@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"?

>                                            -- use @code{whatis} for that
                                             ^^
Please use 3 dashes in a row, not 2.

> +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?

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

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

Thanks again for working on this.