Re: [doc] improve MI varobj introduction

[Vladimir Prus <ghost at cs dot msu dot su>]

On Friday 05 January 2007 00:48, Eli Zaretskii wrote:
> > From: Vladimir Prus <ghost@cs.msu.su>
> > Date: Thu, 04 Jan 2007 21:23:00 +0300
> > 
> > Here's the final patch.
> 
> Thanks.  I have a few comments and suggestions.
> 
> > -When returning the actual values of the objects, this facility allows
> > -for the individual selection of the display format used in the result
> > -creation.  It can be chosen among: binary, decimal, hexadecimal, octal
> > -and natural.  Natural refers to a default format automatically
> > -chosen based on the variable type (like decimal for an @code{int}, hex
> > -for pointers, etc.).
> 
> This fragment was removed, but the new text doesn't mention this
> feature at all.  Was the old text plain wrong (i.e. there's no such
> feature)?  If the feature does exist, I think it should be mentioned.

I did remove it because detailed explanation about display format are too
detailed for the introduction -- it's not a core functionality. The new doc mention
that display format can be changed, and I've just added more docs to
-var-set-format and -var-evaluate-expression so that essential parts of the
above paragraphs are not lost.

> 
> > +Variable object is MI interface to work with expressions.
> 
> Perhaps it's an interface to work with named expressions, because I
> believe you don't need anything to work with just expressions, do you?

Although you can use -data-evaluate-expression, using varobj is the recommended
way. I don't think "named expressions" is the key here -- if MI was an interface
in any object oriented language, you would not need varobj name at all. But since MI
is pipe interface, you need some opaque token instead of object reference in a 
programming language. So no fundamentally named expression are involved.
How about:

	Variable object is the recommended MI interface to work with expressions.

> >                     Child variable objects can children themself,
> > +util we reach leaf variable objects of built-in types. ^^^^^^^^
>    ^^^^
> Typos, and also something's wrong with this sentence in general.

Changed to:


	Child variable objects can themself have children,
	util we reach leaf variable objects of built-in types.

Revised patch attached -- hopefully better this time.

- Volodya

--- gdb/doc/gdb.texinfo	(/patches/gdb/mi_inline_tests/gdb_mainline)	(revision 3054)
+++ gdb/doc/gdb.texinfo	(/patches/gdb/varobj_doc/gdb_mainline)	(revision 3054)
@@ -19570,26 +19570,36 @@ least, the following operations:
 
 @end ignore
 
-@subheading Introduction to Variable Objects in @sc{gdb/mi}
+@subheading Introduction to Variable Objects
 
 @cindex variable objects in @sc{gdb/mi}
-The basic idea behind variable objects is the creation of a named object
-to represent a variable, an expression, a memory location or even a CPU
-register.  For each object created, a set of operations is available for
-examining or changing its properties.
-
-Furthermore, complex data types, such as C structures, are represented
-in a tree format.  For instance, the @code{struct} type variable is the
-root and the children will represent the struct members.  If a child
-is itself of a complex type, it will also have children of its own.
-Appropriate language differences are handled for C, C@t{++} and Java.
-
-When returning the actual values of the objects, this facility allows
-for the individual selection of the display format used in the result
-creation.  It can be chosen among: binary, decimal, hexadecimal, octal
-and natural.  Natural refers to a default format automatically
-chosen based on the variable type (like decimal for an @code{int}, hex
-for pointers, etc.).
+
+Variable object is the recommended MI interface to work with expressions.  
+When creating a variable object, a frontend specifies the name of
+the variable object and an expression in the debugged program.
+Such expression can be a simple variable, or it can be an arbitrary
+complex expression, and can even involve CPU registers.  After
+creating a variable object, the frontend can invoke other variable
+object operations---for example to obtain or change the value of
+a variable object, or to change display format.
+
+Variable objects have hierarchical tree structure.  Any variable object
+that corresponds to a composite type, such as structure in C, has
+a number of child variable objects, for example corresponding to each
+element of a structure.  Child variable objects can themself have children,
+util we reach leaf variable objects of built-in types.
+
+For a leaf variable object it is possible to obtain its value as a
+string, or set the value from a string.  String value can be also
+obtained for a non-leaf variable object, but it's generally a string
+that only indicates the type of the object, and does not list its
+contents.  Assignment to a non-leaf variable object is not allowed.
+ 
+A frontend does not need to read the values of all variable objects each time
+the program stops.  Instead, MI provides an update command that lists all
+variable objects whose values has changed since the last update
+operation.  This considerably reduces the amount of data that must
+be transferred to the frontend.
 
 The following is the complete set of @sc{gdb/mi} operations defined to
 access this functionality:
@@ -19712,6 +19722,12 @@ The syntax for the @var{format-spec} is 
  @{binary | decimal | hexadecimal | octal | natural@}
 @end smallexample
 
+The natural format is the default format choosen automatically
+based on the variable type (like decimal for an @code{int}, hex
+for pointers, etc.).
+
+For a variable with children, the format is set only on the 
+variable itself, and the children are not affected.  
 
 @subheading The @code{-var-show-format} Command
 @findex -var-show-format
@@ -19843,8 +19859,8 @@ where @var{attr} is @code{@{ @{ editable
 @end smallexample
 
 Evaluates the expression that is represented by the specified variable
-object and returns its value as a string in the current format specified
-for the object:
+object and returns its value as a string.  The format of the
+string can be changed using the @code{-var-set-format} command.
 
 @smallexample
  value=@var{value}
@@ -19888,12 +19904,19 @@ subsequent @code{-var-update} list.
  -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
-Update the value of the variable object @var{name} by evaluating its
-expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.  The
-option @var{print-values} determines whether names both and values, or
-just names are printed in the manner described for
-@code{-var-list-children} (@pxref{-var-list-children}).
+Reevaluate the expressions corresponding to the variable object
+@var{name} and all its direct and indirect children, and return the
+list of variable objects whose values have changed. Here,
+``changed'' means that the result of @code{-var-evaluate-expression} before
+and after the @code{-var-update} is different.  If @samp{*} is used
+as the variable object names, all existing variable objects are
+updated.  The option @var{print-values} determines whether both names 
+and values, or just names are printed.  The possible values of
+this options are the same as for @code{-var-list-children}
+(@pxref{-var-list-children}).  It is recommended to use the
+@samp{--all-values} option, to reduce the number of MI commands needed
+on each program stop.
+
 
 @subsubheading Example
 

Property changes on: 
___________________________________________________________________
Name: csl:base
 -/all/patches/gdb/mi_continue_to/gdb_mainline
 +/all/patches/gdb/mi_inline_tests/gdb_mainline
Name: svk:merge
  d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_continue_to/gdb_mainline:2736
 +d48a11ec-ee1c-0410-b3f5-c20844f99675:/patches/gdb/mi_inline_tests/gdb_mainline:3051