[PATCH v2] Fix documentation for Type.template_argument.

[PATCH v2] Fix documentation for Type.template_argument.

[Justin Lebar]

In the Python API, Type.template_argument(n) returns either a gdb.Type
or a gdb.Value, depending on whether the n'th template argument is a C++
type or a C++ value.

Also add a note that Type.template_argument(n) throws an exception if n
is out of range (as opposed to, say, returning None).

There's one piece of the documentation I still don't understand:

> If block is given, then name is looked up in that scope. Otherwise, it
> is searched for globally.

What is 'name', exactly, and why are we looking it up?  I'd be happy to
fix this up if we could clarify this, but otherwise this patch stands on
its own.

2014-06-18  Justin Lebar <jlebar@google.com>

	* python.texi (Types In Python): Type.template_argument(n) returns a
	gdb.Value or a gdb.Type and throws an exception if n is out of
	range.
---
 gdb/doc/python.texi | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 4688783..266af80 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1048,11 +1048,12 @@ exception.
 
 @defun Type.template_argument (n @r{[}, block@r{]})
 If this @code{gdb.Type} is an instantiation of a template, this will
-return a new @code{gdb.Type} which represents the type of the
-@var{n}th template argument.
+return a new @code{gdb.Value} or @code{gdb.Type} which represents the
+value of the @var{n}th template argument (indexed starting at 0).
 
-If this @code{gdb.Type} is not a template type, this will throw an
-exception.  Ordinarily, only C@t{++} code will have template types.
+If this @code{gdb.Type} is not a template type, or if the type has fewer
+than @var{n} template arguments, this will throw an exception.
+Ordinarily, only C@t{++} code will have template types.
 
 If @var{block} is given, then @var{name} is looked up in that scope.
 Otherwise, it is searched for globally.
-- 
2.0.0.526.g5318336

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Justin Lebar]

Ping on this patch?  (Would it be appropriate to find the last person
to touch this documentation and cc him/her, or do something else like
that?)

Regards,
-Justin

On Tue, Jun 24, 2014 at 3:38 PM, Justin Lebar <jlebar@google.com> wrote:
> In the Python API, Type.template_argument(n) returns either a gdb.Type
> or a gdb.Value, depending on whether the n'th template argument is a C++
> type or a C++ value.
>
> Also add a note that Type.template_argument(n) throws an exception if n
> is out of range (as opposed to, say, returning None).
>
> There's one piece of the documentation I still don't understand:
>
>> If block is given, then name is looked up in that scope. Otherwise, it
>> is searched for globally.
>
> What is 'name', exactly, and why are we looking it up?  I'd be happy to
> fix this up if we could clarify this, but otherwise this patch stands on
> its own.
>
> 2014-06-18  Justin Lebar <jlebar@google.com>
>
>         * python.texi (Types In Python): Type.template_argument(n) returns a
>         gdb.Value or a gdb.Type and throws an exception if n is out of
>         range.
> ---
>  gdb/doc/python.texi | 9 +++++----
>  1 file changed, 5 insertions(+), 4 deletions(-)
>
> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index 4688783..266af80 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -1048,11 +1048,12 @@ exception.
>
>  @defun Type.template_argument (n @r{[}, block@r{]})
>  If this @code{gdb.Type} is an instantiation of a template, this will
> -return a new @code{gdb.Type} which represents the type of the
> -@var{n}th template argument.
> +return a new @code{gdb.Value} or @code{gdb.Type} which represents the
> +value of the @var{n}th template argument (indexed starting at 0).
>
> -If this @code{gdb.Type} is not a template type, this will throw an
> -exception.  Ordinarily, only C@t{++} code will have template types.
> +If this @code{gdb.Type} is not a template type, or if the type has fewer
> +than @var{n} template arguments, this will throw an exception.
> +Ordinarily, only C@t{++} code will have template types.
>
>  If @var{block} is given, then @var{name} is looked up in that scope.
>  Otherwise, it is searched for globally.
> --
> 2.0.0.526.g5318336
>

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Joel Brobecker]

> Ping on this patch?  (Would it be appropriate to find the last person
> to touch this documentation and cc him/her, or do something else like
> that?)

No, Eli is the person to review this patch, not the last person to
touch it. Maybe he is away at the moment.

-- 
Joel

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Eli Zaretskii]

> Date: Mon, 7 Jul 2014 07:42:50 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> > Ping on this patch?  (Would it be appropriate to find the last person
> > to touch this documentation and cc him/her, or do something else like
> > that?)
> 
> No, Eli is the person to review this patch, not the last person to
> touch it. Maybe he is away at the moment.

I'm not away, I just remembered that I already reviewed this patch and
responded with the review on the same day.

It looks now that my response didn't make it to the list for some
reason, because I see it in my FCC archive, but not in the list
archives.

So here's my response as I wrote it back then:

  > From: Justin Lebar <jlebar@google.com>
  > Cc: Justin Lebar <jlebar@google.com>
  > Date: Tue, 24 Jun 2014 12:01:36 -0700
  >
  > -If this @code{gdb.Type} is not a template type, this will throw an
  > -exception.  Ordinarily, only C@t{++} code will have template types.
  > +If this @code{gdb.Type} is not a template type, or if the type has fewer
  > +than N template arguments, this will throw an exception.  Ordinarily,
	  ^
  @var{n}

  Otherwise, the patch is OK Texinfo-wise; I don't know enough about
  these issues to tell whether the content is correct, nor can I answer
  your question.

  Thanks.

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Justin Lebar]

> I'm not away, I just remembered that I already reviewed this patch and
> responded with the review on the same day.

Indeed, and although there may have been a problem with the list, I
got your response and sent a fixed patch.  But maybe I misunderstood
your response?

> Otherwise, the patch is OK Texinfo-wise; I don't know enough about
> these issues to tell whether the content is correct

I thought this indicated I should wait for someone else to chime in?
Or were you saying this was OK to submit with this change?

Sorry, I'm obviously new here.  :)

-Justin

On Mon, Jul 7, 2014 at 8:32 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Mon, 7 Jul 2014 07:42:50 -0700
>> From: Joel Brobecker <brobecker@adacore.com>
>> Cc: gdb-patches@sourceware.org
>>
>> > Ping on this patch?  (Would it be appropriate to find the last person
>> > to touch this documentation and cc him/her, or do something else like
>> > that?)
>>
>> No, Eli is the person to review this patch, not the last person to
>> touch it. Maybe he is away at the moment.
>
> I'm not away, I just remembered that I already reviewed this patch and
> responded with the review on the same day.
>
> It looks now that my response didn't make it to the list for some
> reason, because I see it in my FCC archive, but not in the list
> archives.
>
> So here's my response as I wrote it back then:
>
>   > From: Justin Lebar <jlebar@google.com>
>   > Cc: Justin Lebar <jlebar@google.com>
>   > Date: Tue, 24 Jun 2014 12:01:36 -0700
>   >
>   > -If this @code{gdb.Type} is not a template type, this will throw an
>   > -exception.  Ordinarily, only C@t{++} code will have template types.
>   > +If this @code{gdb.Type} is not a template type, or if the type has fewer
>   > +than N template arguments, this will throw an exception.  Ordinarily,
>           ^
>   @var{n}
>
>   Otherwise, the patch is OK Texinfo-wise; I don't know enough about
>   these issues to tell whether the content is correct, nor can I answer
>   your question.
>
>   Thanks.
>

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Eli Zaretskii]

> From: Justin Lebar <jlebar@google.com>
> Date: Mon, 7 Jul 2014 10:28:58 -0700
> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org
> 
> > Otherwise, the patch is OK Texinfo-wise; I don't know enough about
> > these issues to tell whether the content is correct
> 
> I thought this indicated I should wait for someone else to chime in?

You understood correctly.  Since you are correcting existing
documentation, I think it would be good if someone who knows that
stuff looked at the corrections from the contents point of view and
approved them.

Thanks.

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Doug Evans]

On Mon, Jul 7, 2014 at 10:43 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Justin Lebar <jlebar@google.com>
>> Date: Mon, 7 Jul 2014 10:28:58 -0700
>> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org
>>
>> > Otherwise, the patch is OK Texinfo-wise; I don't know enough about
>> > these issues to tell whether the content is correct
>>
>> I thought this indicated I should wait for someone else to chime in?
>
> You understood correctly.  Since you are correcting existing
> documentation, I think it would be good if someone who knows that
> stuff looked at the corrections from the contents point of view and
> approved them.
>
> Thanks.

Content-wise, the patch is ok with me.

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Justin Lebar]

Can we finally submit this patch, or is there something else I need to do here?

On Sun, Aug 17, 2014 at 11:25 AM, Doug Evans <dje@google.com> wrote:
> On Mon, Jul 7, 2014 at 10:43 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>>> From: Justin Lebar <jlebar@google.com>
>>> Date: Mon, 7 Jul 2014 10:28:58 -0700
>>> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org
>>>
>>> > Otherwise, the patch is OK Texinfo-wise; I don't know enough about
>>> > these issues to tell whether the content is correct
>>>
>>> I thought this indicated I should wait for someone else to chime in?
>>
>> You understood correctly.  Since you are correcting existing
>> documentation, I think it would be good if someone who knows that
>> stuff looked at the corrections from the contents point of view and
>> approved them.
>>
>> Thanks.
>
> Content-wise, the patch is ok with me.

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Doug Evans]

Yeah, it's good to go.


On Tue, Sep 2, 2014 at 3:13 PM, Justin Lebar <jlebar@google.com> wrote:
> Can we finally submit this patch, or is there something else I need to do here?
>
> On Sun, Aug 17, 2014 at 11:25 AM, Doug Evans <dje@google.com> wrote:
>> On Mon, Jul 7, 2014 at 10:43 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>>>> From: Justin Lebar <jlebar@google.com>
>>>> Date: Mon, 7 Jul 2014 10:28:58 -0700
>>>> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org
>>>>
>>>> > Otherwise, the patch is OK Texinfo-wise; I don't know enough about
>>>> > these issues to tell whether the content is correct
>>>>
>>>> I thought this indicated I should wait for someone else to chime in?
>>>
>>> You understood correctly.  Since you are correcting existing
>>> documentation, I think it would be good if someone who knows that
>>> stuff looked at the corrections from the contents point of view and
>>> approved them.
>>>
>>> Thanks.
>>
>> Content-wise, the patch is ok with me.

Re: [PATCH v2] Fix documentation for Type.template_argument.

[Doug Evans]

On Tue, Sep 2, 2014 at 3:24 PM, Doug Evans <dje@google.com> wrote:
> Yeah, it's good to go.
>
>
> On Tue, Sep 2, 2014 at 3:13 PM, Justin Lebar <jlebar@google.com> wrote:
>> Can we finally submit this patch, or is there something else I need to do here?
>>
>> On Sun, Aug 17, 2014 at 11:25 AM, Doug Evans <dje@google.com> wrote:
>>> On Mon, Jul 7, 2014 at 10:43 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>>>>> From: Justin Lebar <jlebar@google.com>
>>>>> Date: Mon, 7 Jul 2014 10:28:58 -0700
>>>>> Cc: Joel Brobecker <brobecker@adacore.com>, gdb-patches@sourceware.org
>>>>>
>>>>> > Otherwise, the patch is OK Texinfo-wise; I don't know enough about
>>>>> > these issues to tell whether the content is correct
>>>>>
>>>>> I thought this indicated I should wait for someone else to chime in?
>>>>
>>>> You understood correctly.  Since you are correcting existing
>>>> documentation, I think it would be good if someone who knows that
>>>> stuff looked at the corrections from the contents point of view and
>>>> approved them.
>>>>
>>>> Thanks.
>>>
>>> Content-wise, the patch is ok with me.

Hi.
fyi, I've committed this.