Re: [RFC - Python Scripting] New method Value.referenced_value to dereference pointer as well as reference values (with docs)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 13 Mar 2012 17:23:54 +0530
> From: Siva Chandra <sivachandra@google.com>
> 
> Per Tom's suggestion in another thread (see for reference
> http://sourceware.org/ml/gdb-patches/2012-03/msg00417.html), I have
> added a new method to gdb.Value. I am starting a new mail thread as
> the subject line, and the patch, have changed quite a bit from last
> time.

Thanks.

> +A similar function @code{Value.referenced_value} exists which also
> +returns @code{gdb.Value} objects corresonding to the values pointed to
> +by pointer values (and additionally, values referenced by reference
> +values).  However, the behaviour of @code{Value.dereference}
                          ^^^^^^^^^
Please use the US spelling ("behavior"), here and elsewhere in your
patch.

> +differs with @code{Value.referenced_value} by the fact that the
   ^^^^^^^^^^^^
"differs from"

> +behaviour of @code{Value.dereference} is identical to applying the C
> +unary @code{*} operator on a given value.  For example, consider a
   ^^^^^^^^^^^^^^^^^^^^^^^
"unary operator `*'" sounds better.  (There are more occurrences of
this in the patch.)

> +reference to a pointer @code{ptrref}, declared in your C++ program as

We use C@t{++} instead of C++, the former looks better in print.

> +@smallexample
> +typedef int *intptr;
> +...
> +int val = 10;
> +intptr ptr = &val;
> +intptr &ptrref = ptr;
> +@end smallexample
> +
> +Though @code{ptrref} is a reference value, one can apply the method
> +@code{Value.dereference} on the @code{gdb.Value} object corresponding
                            ^^
"apply ... to"

> +corresponding to @code{ptr}.  In general, @code{Value.dereference} can
> +be applied whenever the C unary @code{*} operator can be legally applied
> +to the corresponding C value.

GNU coding standards frown on using "legally" for anything that
doesn't refer to laws.  Please just drop that word, it doesn't add any
important information in this context.

>                                       For those cases where applying both
> +@code{Value.dereference} and @code{Value.referenced_value} is legal, the
                                                                 ^^^^^
Here, I would use "allowed" or "possible" instead of "legal".

> +results obtained need not be identical (as we have seen in the above
> +example).  The results are however identical when applied on
> +@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value}
> +objects with type code @code{TYPE_CODE_PTR}) in a C/C++ program.
                                                       ^^^
C@t{++}

> +values.  For example, consider a reference to an @code{int}, declared
> +in your C++ program as

And here.

> +@smallexample
> +int val = 10;
> +int &ref = val;
> +@end smallexample
> +
> +then applying @code{Value.dereference} on the @code{gdb.Value} object
                                          ^^
You want @noindent before this line.  And "to", not "on".

OK with those changes, as far as the documentation is concerned.