Re: [doc] improve MI varobj introduction

Nick Roberts
2006-12-20T20:52:56Z

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 and the manual is
about the interface not GDB internals.

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

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

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

--
Nick http://www.inet.net.nz/~nickrob