Re: [doc] improve MI varobj introduction

Vladimir Prus
2006-12-21T06:15:27Z

On Wednesday 20 December 2006 23:48, Nick Roberts wrote:
> Vladimir Prus writes:
> > 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);
>
> I don't follow. AFAICS there is no function mi_assign

Exactly. Therefore, you cannot pass integer value to it. All of MI is purely
text base, so the value you pass to -var-assign is a string. Even if frontend
has

int value;

is has to convert it to string before passing to MI. That's why I say the value is
assigned from a string.

> > 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.
>
> I had no problem when I first read it but in any case it's Eli's call.
>
> > -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.
>
> That's why I suggested _adding_ your paragraph.
>
> > -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.
>
> It tells me variable objects might not work for other languages.

That's not my reading of the above. To say that, the sentence must be:

Variable objects are only supported for programs in C C@t{++} and Java.

As written, we know that some unknown differences between C, C++ and Java are
handled. One has no clue if Pascal is not supported, or appropriate differences with
Pascal are not handled, or maybe if Pascal has no appropriate differences to begin with.

>
> > > 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.
>
> I don't think the manual should recommend ways to use MI commands. I guess
> it could say that
>
> the @samp{--all-values} option reduces the number of MI commands needed +on
> each program stop.
>
> but that should be obvious anyway and we're starting to guess how someone is
> using MI.

I think it's fine that folks hacking on MI have better first approximation to the right
way of using it than somebody how just opened the docs do implement a new
frontend. So, recommending something is quite reasonable.

> > > 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?
>
> The list just after:
>
> The following is the complete set of GDB/MI operations...

I don't have an opinion. If the list was clickable, it would be useful, but it's not,
and I don't know if info can be persuaded that make them clickable (and not
very interested to change that, anyway)

- Volodya

>