[patch][doc] PR python/10781

[patch][doc] PR python/10781

[Phil Muldoon]

On irc,  Michael Lyle noticed that Value.cast was not documented in GDB 
7.0, but the method was available for use. Tom wrote this documentation 
sometime ago, and it got missed on the merge. This patch fixes this.

OK?

Cheers,

Phil

--

ChangeLog

2009-10-16  Tom Tromey <tromey@redhat.com>

     PR python/10781

     * gdb.texinfo (Values From Inferior): Document cast method.

--

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.633
diff -u -r1.633 gdb.texinfo
--- doc/gdb.texinfo    12 Oct 2009 01:59:54 -0000    1.633
+++ doc/gdb.texinfo    16 Oct 2009 07:30:12 -0000
@@ -19232,6 +19232,13 @@
  The following methods are provided:

  @table @code
+@defmethod Value cast type
+Cast the @code{gdb.Value} to the type represented by @var{type}, and
+return a new @code{gdb.Value}.  @var{type} must be a @code{gdb.Type}
+object.  If the cast cannot be performed for some reason, an exception
+is thrown.
+@end defmethod
+
  @defmethod Value dereference
  For pointer data types, this method returns a new @code{gdb.Value} object
  whose contents is the object pointed to by the pointer.  For example, if
[pmuldoon@localhost gdb]$

Re: [patch][doc] PR python/10781

[Eli Zaretskii]

> Date: Fri, 16 Oct 2009 08:35:35 +0100
> From: Phil Muldoon <pmuldoon@redhat.com>
> 
> On irc,  Michael Lyle noticed that Value.cast was not documented in GDB 
> 7.0, but the method was available for use. Tom wrote this documentation 
> sometime ago, and it got missed on the merge. This patch fixes this.
> 
> OK?

I have a few comments:

> +Cast the @code{gdb.Value} to the type represented by @var{type}, and
        ^^^
Please remove this "the".

> +return a new @code{gdb.Value}.  @var{type} must be a @code{gdb.Type}
> +object.

If TYPE is an object, then it probably isn't a good idea to call it
TYPE.  Why not OBJECT?

Anyway, what does it mean "the type represented by TYPE"?  How can a
type be "represented"?  Did you perhaps mean "the type of TYPE"?

>       If the cast cannot be performed for some reason, an exception
> +is thrown.

Suggest to rephrase to avoid passive tense.

Thanks.

Re: [patch][doc] PR python/10781

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> +Cast the @code{gdb.Value} to the type represented by @var{type}, and
Eli>         ^^^
Eli> Please remove this "the".

Removing the "the" makes this read strangely.
gdb.Value is a class, the "the" indicates that it is an instance which is
cast.

>> +return a new @code{gdb.Value}.  @var{type} must be a @code{gdb.Type}
>> +object.

Eli> If TYPE is an object, then it probably isn't a good idea to call it
Eli> TYPE.  Why not OBJECT?

I think it is generally preferable to name parameters according to their
use.  "object" is not specific enough.

Eli> Anyway, what does it mean "the type represented by TYPE"?  How can a
Eli> type be "represented"?  Did you perhaps mean "the type of TYPE"?

gdb.Type represents a type in the inferior.
"the type of TYPE" would be incorrect.

Tom

Re: [patch][doc] PR python/10781

[Eli Zaretskii]

> From: Tom Tromey <tromey@redhat.com>
> Cc: Phil Muldoon <pmuldoon@redhat.com>, gdb-patches@sourceware.org
> Date: Fri, 16 Oct 2009 12:07:01 -0600
> 
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> +Cast the @code{gdb.Value} to the type represented by @var{type}, and
> Eli>         ^^^
> Eli> Please remove this "the".
> 
> Removing the "the" makes this read strangely.
> gdb.Value is a class, the "the" indicates that it is an instance which is
> cast.

Then how about "Cast an instance of @code{gdb.Value} ..."?

> >> +return a new @code{gdb.Value}.  @var{type} must be a @code{gdb.Type}
> >> +object.
> 
> Eli> If TYPE is an object, then it probably isn't a good idea to call it
> Eli> TYPE.  Why not OBJECT?
> 
> I think it is generally preferable to name parameters according to their
> use.

No, they should be named according to their essence, i.e. what they
are.

> "object" is not specific enough.

I'm open to other suggestions.

> Eli> Anyway, what does it mean "the type represented by TYPE"?  How can a
> Eli> type be "represented"?  Did you perhaps mean "the type of TYPE"?
> 
> gdb.Type represents a type in the inferior.

Sorry, I still don't understand.

Re: [patch][doc] PR python/10781

[Tom Tromey]

Eli> Then how about "Cast an instance of @code{gdb.Value} ..."?

Maybe "this instance".
It is not any instance.

>> I think it is generally preferable to name parameters according to their
>> use.

Eli> No, they should be named according to their essence, i.e. what they
Eli> are.

It must be a type -- an instance of gdb.Type.

>> gdb.Type represents a type in the inferior.

Eli> Sorry, I still don't understand.

gdb.Type is a class.  An instance of this class represents a type in the
user's program.  It is a representation because it is not actually the
type, but a way of describing the type.

Tom

Re: [patch][doc] PR python/10781

[Eli Zaretskii]

Here's the text that I propose to use:

    +@defmethod Value cast type
    +Return a new instance of @code{gdb.Value} that is the result of
    +casting this instance to the type described by @var{type},
    +which must be a @code{gdb.Type} object.  If the cast cannot be
    +performed for some reason, this method throws an exception.
    +@end defmethod

Re: [patch][doc] PR python/10781

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> Here's the text that I propose to use:
Eli>     +@defmethod Value cast type
Eli>     +Return a new instance of @code{gdb.Value} that is the result of
Eli>     +casting this instance to the type described by @var{type},
Eli>     +which must be a @code{gdb.Type} object.  If the cast cannot be
Eli>     +performed for some reason, this method throws an exception.
Eli>     +@end defmethod

Looks good to me.

Tom

Re: [patch][doc] PR python/10781

[Phil Muldoon]

On 10/16/2009 08:08 PM, Eli Zaretskii wrote:
> Here's the text that I propose to use:
>
>      +@defmethod Value cast type
>      +Return a new instance of @code{gdb.Value} that is the result of
>      +casting this instance to the type described by @var{type},
>      +which must be a @code{gdb.Type} object.  If the cast cannot be
>      +performed for some reason, this method throws an exception.
>      +@end defmethod
>    

Ok to check this patch in?

ChangeLog

2009-10-27  Tom Tromey <tromey@redhat.com>
                      Eli Zaretskii <eliz@gnu.org>

               PR python/10781

                * gdb.texinfo (Values From Inferior): Document cast method.

--

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.637
diff -u -r1.637 gdb.texinfo
--- doc/gdb.texinfo    23 Oct 2009 00:49:32 -0000    1.637
+++ doc/gdb.texinfo    27 Oct 2009 15:48:10 -0000
@@ -19445,6 +19445,13 @@
  The following methods are provided:

  @table @code
+@defmethod Value cast type
+Return a new instance of @code{gdb.Value} that is the result of
+casting this instance to the type described by @var{type}, which must
+be a @code{gdb.Type} object.  If the cast cannot be performed for some
+reason, this method throws an exception.
+@end defmethod
+

Re: [patch][doc] PR python/10781

[Phil Muldoon]

On 10/27/2009 03:52 PM, Phil Muldoon wrote:
> On 10/16/2009 08:08 PM, Eli Zaretskii wrote:
>> Here's the text that I propose to use:
>>
>>      +@defmethod Value cast type
>>      +Return a new instance of @code{gdb.Value} that is the result of
>>      +casting this instance to the type described by @var{type},
>>      +which must be a @code{gdb.Type} object.  If the cast cannot be
>>      +performed for some reason, this method throws an exception.
>>      +@end defmethod
>
> Ok to check this patch in?
>
> ChangeLog
>
> 2009-10-27  Tom Tromey <tromey@redhat.com>
>                      Eli Zaretskii <eliz@gnu.org>
>
>               PR python/10781
>
>                * gdb.texinfo (Values From Inferior): Document cast 
> method.


Apart from the obvious ChangeLog formatting oops (not sure what happened 
there, but it will be correctly formatted on commit).

Cheers,

Phl

Re: [patch][doc] PR python/10781

[Eli Zaretskii]

> Date: Tue, 27 Oct 2009 15:52:03 +0000
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: Tom Tromey <tromey@redhat.com>, gdb-patches@sourceware.org
> 
> On 10/16/2009 08:08 PM, Eli Zaretskii wrote:
> > Here's the text that I propose to use:
> >
> >      +@defmethod Value cast type
> >      +Return a new instance of @code{gdb.Value} that is the result of
> >      +casting this instance to the type described by @var{type},
> >      +which must be a @code{gdb.Type} object.  If the cast cannot be
> >      +performed for some reason, this method throws an exception.
> >      +@end defmethod
> >    
> 
> Ok to check this patch in?

If you are asking me, the answer is obviously yes, since it's text I
wrote.

Re: [patch][doc] PR python/10781

[Phil Muldoon]

On 10/27/2009 06:42 PM, Eli Zaretskii wrote:
>> Date: Tue, 27 Oct 2009 15:52:03 +0000
>> From: Phil Muldoon<pmuldoon@redhat.com>
>> CC: Tom Tromey<tromey@redhat.com>, gdb-patches@sourceware.org
>>
>> On 10/16/2009 08:08 PM, Eli Zaretskii wrote:
>>      
>>> Here's the text that I propose to use:
>>>
>>>       +@defmethod Value cast type
>>>       +Return a new instance of @code{gdb.Value} that is the result of
>>>       +casting this instance to the type described by @var{type},
>>>       +which must be a @code{gdb.Type} object.  If the cast cannot be
>>>       +performed for some reason, this method throws an exception.
>>>       +@end defmethod
>>>
>>>        
>> Ok to check this patch in?
>>      
> If you are asking me, the answer is obviously yes,


Ok, thanks. Checked in.


> since it's text I
> wrote.
>    


I was being deferential.  The patch was based on text that was already 
written, and rewritten by another at a later date.  I as purely being 
the facilitator to fix a bug reported by a user.  I encouraged that user 
to file the bug,  and I decided to make sure the various patches were 
filed. I decided it was best to check in this case.

Cheers!

Phil

Re: [patch][doc] PR python/10781

[Eli Zaretskii]

> Date: Tue, 27 Oct 2009 20:57:52 +0000
> From: Phil Muldoon <pmuldoon@redhat.com>
> CC: tromey@redhat.com, gdb-patches@sourceware.org
> 
> >> Ok to check this patch in?
> >>      
> > If you are asking me, the answer is obviously yes,
> 
> 
> Ok, thanks. Checked in.

Thank you.