Re: [doc] improve MI varobj introduction

Vladimir Prus
2007-01-04T18:23:57Z

[-- Attachment #1: Type: text/plain, Size: 652 bytes --]

Daniel Jacobowitz wrote:

> On Tue, Dec 26, 2006 at 06:51:54PM +0300, Vladimir Prus wrote:
>> > I didn't really follow this thread, but I would recommend posting a
>> > revised version of the patch with any changes when you're ready to.
>>
>> I don't have any planned changes so far, except for three-word editorial
>> change suggested by Nick.
>
> Right, but a final patch is still helpful - it lets a reviewer
> (probably Eli) look at what you have without having to follow the
> discussion.

Here's the final patch.

- Volodya

* gdb.texinfo (GDB/MI Variable Objects): Improve the
introduction. Specify -var-update more exactly.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: varobj_doc__gdb_mainline.diff --]
[-- Type: text/x-diff; name="varobj_doc__gdb_mainline.diff", Size: 4687 bytes --]

--- gdb/doc/gdb.texinfo (/patches/gdb/mi_inline_tests/gdb_mainline) (revision 3043)
+++ gdb/doc/gdb.texinfo (/patches/gdb/varobj_doc/gdb_mainline) (revision 3043)
@@ -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 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 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 children themself,
+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 its generally a string
+that only indicates the type of the object, and does not list its
+content. Assignment to a non-leaf variable object is not allowed.
+
+A frontend need not read the values of all variable objects each time
+the program stops. Instead, MI provides update command that lists all
+variable objects which 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:
@@ -19888,12 +19898,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 which 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:3041