[python] update documentation

[Tom Tromey <tromey at redhat dot com>]

This updates the varobj documentation to reflect current reality, to the
best of my knowledge.

Tom

2009-09-04  Tom Tromey  <tromey@redhat.com>

	* gdb.texinfo (GDB/MI Variable Objects): Use @value.  Define
	dynamic varobj.  Update -var-list-children and -var-update
	documentation.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 1042303..0e92ac7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23774,14 +23774,14 @@ how it can be used.
 -enable-pretty-printing
 @end smallexample
 
-@var{GDBN} allows Python-based visualizers to affect the output of the
+@value{GDBN} allows Python-based visualizers to affect the output of the
 MI variable object commands.  However, because there was no way to
 implement this in a fully backward-compatible way, a front end must
 request that this functionality be enabled.
 
 Once sent, this command cannot be undone.
 
-Note that if Python support has not been compiled into @var{GDBN},
+Note that if Python support has not been compiled into @value{GDBN},
 this command will still succeed.
 
 @subheading The @code{-var-create} Command
@@ -23823,15 +23823,50 @@ begin with a @samp{*}), or one of the following:
 @samp{$@var{regname}} --- a CPU register name
 @end itemize
 
+A varobj's may be provided by a Python-based pretty-printer.  In this
+case the varobj is known as a @dfn{dynamic varobj}.  Dynamic varobjs
+have slightly different semantics in some cases.  If the
+@code{-enable-pretty-printing} command is not sent, then @value{GDBN}
+will never create a dynamic varobj.  This ensures backward
+compatibility for existing clients.
+
 @subsubheading Result
 
-This operation returns the name, number of children and the type of the
-object created.  Type is returned as a string as the ones generated by
-the @value{GDBN} CLI.  If a fixed variable object is bound to a
-specific thread, the thread is is also printed:
+This operation returns attributes of the newly-created varobj.  These
+include, but are not limited to:
+
+@table @samp
+@item name
+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.
+
+@item value
+The varobj's scalar value.  For a varobj whose type is some sort of
+aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
+will not be interesting.
+
+@item type
+The varobj's type.  This is a string representation of the type, as
+would be printed by the @value{GDBN} CLI.
+
+@item thread-id
+If a fixed 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.
+@end table
+
+Typical output will look like this:
 
 @smallexample
- name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
+  has_more="@var{has_more}"
 @end smallexample
 
 
@@ -23909,6 +23944,10 @@ 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.
+
 
 @subheading The @code{-var-list-children} Command
 @findex -var-list-children
@@ -23935,6 +23974,16 @@ reset and all children will be reported.  Otherwise, children starting
 at @var{from} (zero-based) and ending just before @var{to} will be
 reported.
 
+If a child range is requested, it will not affect the range of
+children reported by a future call to @code{-var-update}.  For this,
+you must instead use @code{-var-set-update-range}.  The intent of this
+approach is to enable a front end to implement any update approach it
+likes; for example, scrolling a view may cause the front end to
+request more children with @code{-var-list-children}, and 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.
+
 For each child the following results are returned:
 
 @table @var
@@ -23951,8 +24000,13 @@ designate access qualifiers.  For these pseudo children @var{exp} is
 @samp{public}, @samp{private}, or @samp{protected}.  In this case the
 type and value are not present.
 
+For a dynamic varobj, this value cannot reliably be used to form an
+expression.  Also, a dynamic varobj will not report the access
+qualifying pseudo-children, regardless of the language.
+
 @item numchild
-Number of children this child has.
+Number of children this child has.  For a dynamic varobj, this will be
+0.
 
 @item type
 The type of the child.
@@ -23970,7 +24024,12 @@ If the variable object is frozen, this variable will be present with a value of
 
 The result may have its own attributes:
 
-@table @var
+@table @samp
+@item displayhint
+A dynamic varobj can supply a display hint to the front end.  The
+comes directly from the Python pretty-printer object's
+@code{display_hint} method.  @xref{Pretty Printing}.
+
 @item has_more
 This is an integer attribute which is nonzero if there are children
 remaining after the end of the selected range.
@@ -24052,6 +24111,9 @@ result can be used only for UI presentation.  Typical use of
 the @code{-var-info-path-expression} command is creating a 
 watchpoint from a variable object.
 
+This command is currently not valid for children of a dynamic varobj,
+and will give an error when invoked on one.
+
 For example, suppose @code{C} is a C@t{++} class, derived from class
 @code{Base}, and that the @code{Base} class has a member called
 @code{m_size}.  Assume a variable @code{c} is has the type of
@@ -24160,6 +24222,60 @@ diagnostic.
 If @code{-var-set-update-range} was previously used on a varobj, then
 only the selected range of children will be reported.
 
+@code{-var-update} reports all the changed varobjs in a tuple named
+@samp{changelist}.
+
+Each item in the change list is itself a tuple holding:
+
+@table @samp
+@item name
+The name of the varobj.
+
+@item value
+If values were requested for this update, then this field will be
+present and will hold the value of the varobj.
+
+@item in_scope
+This is a string, either @samp{false} if the varobj is not in scope,
+or @samp{true} if it is in scope.
+
+@item type_changed
+This is only present if the varobj is still valid.  If the type
+changed, then this will be the string @samp{true}; otherwise it will
+be @samp{false}.
+
+@item new_type
+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.
+
+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.
+
+The @samp{new_num_children} attribute only reports changes to the
+number of children known by @value{GDBN}.  This is the only way to
+detect whether an update has removed children (which necessarily can
+only happen at the end of the update range).
+
+@item displayhint
+The display hint, if any.
+
+@item has_more
+This is an integer value, which will be 1 if there are more children
+available outside the varobj's update range.
+
+@item new_children
+If new children were added to a dynamic varobj within the selected
+update range (as set by @code{-var-set-update-range}), then they will
+be listed in this attribute.
+@end table
+
 @subsubheading Example
 
 @smallexample