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

[Yao Qi <yao@codesourcery.com>]

gdb/doc:

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

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

diff --git a/gdb/NEWS b/gdb/NEWS
index 7fc3669..d77f75f 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 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..0c9bfd9 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
+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
@@ -32556,8 +32561,9 @@ 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.
+reliable for a dynamic varobj or for a non-dynamic varobj if the
+@samp{--available-children-only} option was specified.  Instead, you
+must examine the @samp{has_more} attribute.
 
 @item value
 The varobj's scalar value.  For a varobj whose type is some sort of
@@ -32576,8 +32582,11 @@ If a variable object is bound to a specific thread, then this is the
 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.
+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.
 
 @item dynamic
 This attribute will be present and have the value @samp{1} if the
@@ -32663,7 +32672,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 +32681,19 @@ Returns the number of children of a variable object @var{name}:
  numchild=@var{n}
 @end smallexample
 
-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.
+If the @samp{--available-children-only} option is specified, then only
+available or collected children of the varobj are considered.
+
+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.
 
+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.
 
 @subheading The @code{-var-list-children} Command
 @findex -var-list-children
@@ -32683,7 +32701,9 @@ 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 +32732,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
+available or collected children of the varobj are considered.
+
+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.
+
 For each child the following results are returned:
 
 @table @var
@@ -33021,8 +33050,12 @@ If the varobj's type changed, then this field will be present and will
 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.
+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.
 
 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 +35329,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