[RFA] Document fixed/floating variable objects and thread-id.

[Vladimir Prus <vladimir@codesourcery.com>]

This patch adds some more docs about variable objects. Even
though floating variable objects have know bugs, I think their
intended behaviour is sufficiently clear right now to document.

- Volodya

	* gdb/doc/gdb.texinfo (gdb/mi Variable object): Document
	fixed and floating variable objects, and clarify that
	a variable object can also be found to a thread.  Update
	-var-create example.
---
 gdb/doc/gdb.texinfo |   32 +++++++++++++++++++++++++-------
 1 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index c73a6d9..4c0b3b9 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -19900,7 +19900,23 @@ relatively slow for embedded targets, so a frontend might want
 to disable automatic update for the variables that are either not
 visible on the screen, or ``closed''.  This is possible using so
 called ``frozen variable objects''.  Such variable objects are never
-implicitly updated.  
+implicitly updated.
+
+Variable objects can be either ``fixed'' or ``floating''. For the
+fixed variable object, the expression is parsed when the variable
+object is created, including associating indentifiers to specific
+variables.  The meaning of expression never changes.  A floating 
+variable object has its expression reparsed each time the variable
+object is updated.  In particular, the meaning of identifiers can
+change every time.
+
+If an expression specified when creating a fixed variable object
+refers to a local variable, the variable object becomes bound to the 
+frame the local variable belongs to.  For multithreaded programs, the
+variable object also becomes bound to the thread.  When such variable
+object is updated, @value{GDBN} makes sure that the thread/frame
+combination the variable object is bound to still exists, and
+re-evaluates the variable object in that thread/frame.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19951,7 +19967,7 @@ how it can be used.
 
 @smallexample
  -var-create @{@var{name} | "-"@}
-    @{@var{frame-addr} | "*"@} @var{expression}
+    @{@var{frame-addr} | "*" | "@"@} @var{expression}
 @end smallexample
 
 This operation creates a variable object, which allows the monitoring of
@@ -19961,12 +19977,13 @@ register.
 The @var{name} parameter is the string by which the object can be
 referenced.  It must be unique.  If @samp{-} is specified, the varobj
 system will generate a string ``varNNNNNN'' automatically.  It will be
-unique provided that one does not specify @var{name} on that format.
-The command fails if a duplicate name is found.
+unique provided that one does not explicitly specifies @var{name} of
+that format.  The command fails if a duplicate name is found.
 
 The frame under which the expression should be evaluated can be
 specified by @var{frame-addr}.  A @samp{*} indicates that the current
-frame should be used.
+frame should be used. A @samp{*} indicates that a floating variable
+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:
@@ -19986,10 +20003,11 @@ begin with a @samp{*}), or one of the following:
 
 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:
+the @value{GDBN} CLI.  If a fixed variable object is bound to a
+specific thread, the thread is is also printed:
 
 @smallexample
- name="@var{name}",numchild="N",type="@var{type}"
+ name="@var{name}",numchild="N",type="@var{type}",thread-id="M"
 @end smallexample
 
 
-- 
1.5.3.5