Re: [doc] improve MI varobj introduction

[Vladimir Prus <vladimir@codesourcery.com>]

On Wednesday 20 December 2006 01:24, Nick Roberts wrote:
> 
> I think it's a good idea to add this.
> 
>  > +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
>                                     ^^^^^^
> -var-assign var1 8  <- not a string
> ^done,value="8"

Actually, it is. The entire MI interface is based on strings. You cannot do:

	int value;
	mi_assign("V", value);

>  > +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.
> 
> and this:
> 
>  > +                                                   and return the
>  > +list of variable object which values has changed as the result.
> 
>                                                        and return the
>     list of variable object whose values have changed.

Ok.

> However, I'm not sure that the replaced parts of the introduction are an
> improvement, 

You mean the first two paragraphs? Let me go though them:

	- The basic idea behind variable objects is the creation 

This passage is just awkward, if not grammatically wrong.

	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.

"Examining or changing its properties" is very vague. This is the first paragraph
of the introduction to MI varobjs, it should explicitly say what user might want
to use them for -- and abstract "property" is not explicit enough.

	-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.

This is not so bad, but it fails to describe important properties of this tree --
namely that only leafs carry any data.

	-Appropriate language differences are handled for C, C@t{++} and Java.

This sentence is content-free. It's pretty obvious that a debugger cannot be
language-agnostic, and it's not clear that "Appropriate" differences are
and why would I care.


> or that elaborating on the PRINT-VALUES option is a good idea. 

You mean the suggestion to use --all-values. I think it's important information,
and given that we have just one MI doc document, it's natural to include this
information. MI docs presently have too little content, not too much.

> Also expanding the introduction allows the removal of the summary of commands
> which just duplicates what comes after.

I'm not sure -- which summaries can be removed now?

- Volodya


>