Re: [PATCH 12/12] NEWS and Doc on --available-children-only

[Yao Qi <yao at codesourcery dot com>]

On 02/14/2014 05:40 PM, Eli Zaretskii wrote:
> This doesn't really say much about the new option, because what
> "available children" means is not explained at all.  Can you add a
> sentence about that, or, better, reword this sentence
> 
>   When used, only the available children are displayed.
> 
> so that the second part explains which children will be displayed and
> which won't?

IMO, "available children" is not a new term in GDB.  We've already had
some in doc:

  Note that this number is not completely reliable for a dynamic varobj.
  It will return the current number of children, but more children may
                                                          ^^^^^^^^^^^^
  be available.
  ^^^^^^^^^^^^^

  The @samp{numchild} field in other varobj responses is generally not
  valid for a dynamic varobj -- it will show the number of children that
  @value{GDBN} knows about, but because dynamic varobjs lazily
  instantiate their children, this will not reflect the number of
  children which may be available.
  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

"available children" means children, whose values are available, or
value available children.  How about replacing "available children"
with "value available children"?  Is it clear?

> 
>> >  The number of children of the varobj.  This number is not necessarily
>> > -reliable for a dynamic varobj.  Instead, you must examine the
>> > -@samp{has_more} attribute.
>> > +reliable for a dynamic varobj or for a non-dynamic varobj if the
>> > +@samp{--available-children-only} option was specified.
> When --available-children-only is specified, isn't it true that this
> number is unreliable for _any_ varobj?  If so, please rephrase to make
> that explicit.
> 

OK.  I mention that explicitly in doc.

>> > -For a dynamic varobj, this indicates whether there appear to be any
>> > -children available.  For a non-dynamic varobj, this will be 0.
>> > +For a dynamic varobj, or for a non-dynamic varobj when the
>> > +@samp{--available-children-only} option is specified, this indicates
>> > +whether there appear to be more children that haven't been listed yet,
>> > +which can be listed with a following @code{-var-list-children}
>> > +command.  For the other cases, this will be 0.
> Same here.
> 

Fixed.

>> > +Note that this number is not completely reliable for a dynamic varobj
>> > +or for a non-dynamic varobj that is listing only available or
>> > +collected children.  It will return the current number of children,
>> > +but more children may be available.
> And here.
> 

Fixed.

>> > +If for a given varobj, the presence of the
>> > +@samp{--available-children-only} option changes between invocations of
>> > +the @code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, the list of children is
>> > +reinitialized.
> "Presence of the ... option changes" sounds awkward.  Does this
> sentence say anything important?  IOW, does reinitialization of the
> list of children have any user-visible effects?  If not, perhaps it is
> better to delete it.  If you think this is needed, then I'd rephrase
> like this:

IMO, it has user-visible effects, which describes the expected behaviour
 of sequence "-var-create --available-children-only" and
"-var-list-children".  This is important to MI front end.

> 
>  If you use any of the commands @code{-var-create},
>  @code{-var-list-children}, or @code{-var-info-num-children} with the
>  @samp{--available-children-only} option followed by any of these
>  commands without that option, or vice versa, the list of children is
>  reinitialized.

It is good to me.  I'll pick it up.

> 
>> >  @smallexample
>> > - -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
>> > + -var-list-children
>> > +   [--available-children-only]
>> > +   [@var{print-values}] @var{name} [@var{from} @var{to}]
>> >  @end smallexample
> Will the reader understand that this is one long line broken for
> readability?  If not, perhaps you should tell that explicitly.
> 

Oh, let us put them in a single line to avoid confusion.

>> > +If the @samp{--available-children-only} option is specified, then only
>> > +available or collected children of the varobj are considered.
> Once again, "available children" needs to be explained.
> 
>> > +If for a given varobj, the presence of the
>> > +@samp{--available-children-only} option changes between invocations of
>> > +the @code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, the list of children is
>> > +reinitialized.
> Same comment as above.
> 
>> >  @item new_num_children
>> > -For a dynamic varobj, if the number of children changed, or if the
>> > -type changed, this will be the new number of children.
>> > +For a dynamic varobj, or non-dynamic varobj that had been created as
>> > +consequence of the @samp{--available-children-only} option to the
>> > +@code{-var-create}, @code{-var-list-children} or
>> > +@code{-var-info-num-children} commands, if the number of children
>> > +changed, or if the type changed, this will be the new number of
>> > +children.
> This sentence is now too long and complicated to be clear.  Suggest to
> break into 2 sentences.  E.g., leave the original sentence as is, and
> then add something like
> 
>   Similarly for a non-dynamic varobj that was created as result of the
>   @samp{--available-children-only} option ...
> 

Fixed as you suggested.  How about the updated patch below?

-- 
Yao (éå)

gdb/doc:

2014-02-17  Pedro Alves  <pedro@codesourcery.com>
	    Yao Qi  <yao@codesourcery.com>

	* gdb.texinfo (GDB/MI Variable Objects): Update doc of MI
	commands "-var-create", "-var-info-num-children" and
	"-var-list-children".
	(GDB/MI Support Commands): Document the new
	"available-children-only" entry in the output of the
	"-list-features" command.

gdb:
2014-02-17  Yao Qi  <yao@codesourcery.com>

	* NEWS: Mention new option "--available-children-only".
---
 gdb/NEWS            |    7 +++++++
 gdb/doc/gdb.texinfo |   47 +++++++++++++++++++++++++++++++++++++++++------
 2 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 7fc3669..1eff6b3 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -90,6 +90,13 @@ PowerPC64 GNU/Linux little-endian	powerpc64le-*-linux*
   ** The commands -break-passcount and -break-commands accept convenience
      variable as breakpoint number.
 
+  ** The commands -var-create, -var-info-num-children and
+     -var-list-children now accept an option
+     "--available-children-only".  When used, only the value available
+     children are displayed.  Support for this feature can be verified
+     using the "-list-features" command, which should contain
+     "available-children-only".
+
 *** Changes in GDB 7.7
 
 * Improved support for process record-replay and reverse debugging on
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 035573e..03d395f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -32504,7 +32504,7 @@ may work differently in future versions of @value{GDBN}.
 @subsubheading Synopsis
 
 @smallexample
- -var-create @{@var{name} | "-"@}
+ -var-create [--available-children-only] @{@var{name} | "-"@}
     @{@var{frame-addr} | "*" | "@@"@} @var{expression}
 @end smallexample
 
@@ -32526,6 +32526,11 @@ object must be created.
 @var{expression} is any expression valid on the current language set (must not
 begin with a @samp{*}), or one of the following:
 
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+This affects the @samp{numchild} and @samp{has_more} attributes in the
+output result.
+
 @itemize @bullet
 @item
 @samp{*@var{addr}}, where @var{addr} is the address of a memory cell
@@ -32557,7 +32562,8 @@ The name of the varobj.
 @item numchild
 The number of children of the varobj.  This number is not necessarily
 reliable for a dynamic varobj.  Instead, you must examine the
-@samp{has_more} attribute.
+@samp{has_more} attribute.  If the @samp{--available-children-only}
+option was specified, this number is not reliable either.
 
 @item value
 The varobj's scalar value.  For a varobj whose type is some sort of
@@ -32577,7 +32583,9 @@ thread's identifier.
 
 @item has_more
 For a dynamic varobj, this indicates whether there appear to be any
-children available.  For a non-dynamic varobj, this will be 0.
+children available.  When the @samp{--available-children-only} option
+is specified, this indicates whether there appear to be more children
+that haven't been listed yet.  For the other cases, this will be 0.
 
 @item dynamic
 This attribute will be present and have the value @samp{1} if the
@@ -32663,7 +32671,7 @@ Returns the format used to display the value of the object @var{name}.
 @subsubheading Synopsis
 
 @smallexample
- -var-info-num-children @var{name}
+ -var-info-num-children [--available-children-only] @var{name}
 @end smallexample
 
 Returns the number of children of a variable object @var{name}:
@@ -32672,10 +32680,20 @@ Returns the number of children of a variable object @var{name}:
  numchild=@var{n}
 @end smallexample
 
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+
 Note that this number is not completely reliable for a dynamic varobj.
+When the @samp{--available-children-only} option is specified, this
+number is not reliable either for a varobj.
 It will return the current number of children, but more children may
 be available.
 
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
 
 @subheading The @code{-var-list-children} Command
 @findex -var-list-children
@@ -32683,7 +32701,7 @@ be available.
 @subsubheading Synopsis
 
 @smallexample
- -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
+ -var-list-children [--available-children-only] [@var{print-values}] @var{name} [@var{from} @var{to}]
 @end smallexample
 @anchor{-var-list-children}
 
@@ -32712,6 +32730,15 @@ then the front end could call @code{-var-set-update-range} with a
 different range to ensure that future updates are restricted to just
 the visible items.
 
+If the @samp{--available-children-only} option is specified, then only
+value available or collected children of the varobj are considered.
+
+If you use any of the commands @code{-var-create},
+@code{-var-list-children}, or @code{-var-info-num-children} with the
+@samp{--available-children-only} option followed by any of these
+commands without that option, or vice versa, the list of children is
+reinitialized.
+
 For each child the following results are returned:
 
 @table @var
@@ -33022,7 +33049,10 @@ hold the new type.
 
 @item new_num_children
 For a dynamic varobj, if the number of children changed, or if the
-type changed, this will be the new number of children.
+type changed, this will be the new number of children.  Similarly
+for a non-dynamic varobj that was created as result of the
+@samp{--available-children-only} option to the @code{-var-create},
+@code{-var-list-children} or @code{-var-info-num-children} commands.
 
 The @samp{numchild} field in other varobj responses is generally not
 valid for a dynamic varobj -- it will show the number of children that
@@ -35296,6 +35326,11 @@ records, produced when trying to execute an undefined @sc{gdb/mi} command
 @item exec-run-start-option
 Indicates that the @code{-exec-run} command supports the @option{--start}
 option (@pxref{GDB/MI Program Execution}).
+@item available-children-only
+Indicates that the @code{-var-create}, @code{-var-info-num-children}
+and @code{-var-list-children} commands support the
+@option{--available-children-only}.
+
 @end ftable
 
 @subheading The @code{-list-target-features} Command
-- 
1.7.7.6