Re: [doc] improve MI varobj introduction

[Vladimir Prus <ghost@cs.msu.su>]

Eli Zaretskii wrote:

>> From: Vladimir Prus <ghost@cs.msu.su>
>> Date: Fri, 5 Jan 2007 11:39:09 +0300
>> Cc: drow@false.org,
>>  gdb-patches@sources.redhat.com
>> 
>> > > +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.
> 
> This doesn't give a clue why it is the recommended way.  I have
> another suggestion, based on what you explained above:
> 
>   Variable objects are an MI convenience feature to reference
>   expressions.  When a frontend creates a variable object, it
>   specifies a name for an arbitrary expression in the debugged
>   program.  That name can henceforth be used as an opaque handle for
>   the expression.  The expression can be a simple variable, or it can
>   be ...
> 
> Okay?

You're right that my text did not say why it's recommended, but I think the
above is also not accurate. "convenient feature to reference expressions"
is not quite right -- it sounds like varobj is just a method to create
aliases for expression, and varobjs are much more than that. How about:

        Variable objects are "object-oriented" MI interface for
        examining and changing values of expressions. Unlike some other
        MI interfaces that work with expressions, variable objects are
        specifically designed for simple and efficient 
        presentation in the frontend. A variable object is identified
        by string name. When a variable object is created, the
        frontend specifies the expression for that variable object.
        The expression can be a simple variable ........

        
>> > >                     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.
> 
> Hmmm... something is still wrong.  I think you meant this:
> 
>   A child variable object can itself have children, until we reach
>   leaf variable objects which have built-in types.

That looks fine for me, but should not we have a command before "which"?
Otherwise, it sounds like there are two kind of leaf variable objects --
those of builtin types and those of non-builtin types.

- Volodya