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

[Yao Qi <yao@codesourcery.com>]

On 02/18/2014 01:11 PM, Eli Zaretskii wrote:
> OK, thanks.  I think I understand.  I suggest, instead of this:
> 
>   If the @samp{--available-children-only} option is specified, then only
>   value available or collected children of the varobj are considered.
> 
> to say this:
> 
>   If the @samp{--available-children-only} option is specified, then
>   @value(GDBN) considers only those children of the varobj whose
>   values were collected.
> 
> And in general, use "collected values" and "children whose values were
> collected" or "children with collected values" in other places.
> 
> Does this correctly capture your intent?

Yes, that is good to me.  Here is the updated one.

-- 
Yao (齐尧)

gdb/doc:

2014-02-18  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-18  Yao Qi  <yao@codesourcery.com>

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

diff --git a/gdb/NEWS b/gdb/NEWS
index 7fc3669..06d7634 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 children with
+     collected values 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..87cb26f 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,13 @@ 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
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
+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 +32564,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 for any varobj.
 
 @item value
 The varobj's scalar value.  For a varobj whose type is some sort of
@@ -32577,7 +32585,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 +32673,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 +32682,21 @@ 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
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
 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 for any 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 +32704,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 +32733,16 @@ 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
+@value(GDBN) considers only those children of the varobj whose
+values were collected.
+
+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 +33053,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 +35330,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