Re: [PATCH 12/12] NEWS and Doc on --available-children-only

[Eli Zaretskii <eliz@gnu.org>]

> Date: Mon, 17 Feb 2014 17:44:20 +0800
> From: Yao Qi <yao@codesourcery.com>
> CC: <gdb-patches@sourceware.org>
> 
> On 02/14/2014 05:40 PM, Eli Zaretskii wrote:
> > This doesn't really say much about the new option, because what
> > "available children" means is not explained at all.  Can you add a
> > sentence about that, or, better, reword this sentence
> > 
> >   When used, only the available children are displayed.
> > 
> > so that the second part explains which children will be displayed and
> > which won't?
> 
> IMO, "available children" is not a new term in GDB.  We've already had
> some in doc:
> 
>   Note that this number is not completely reliable for a dynamic varobj.
>   It will return the current number of children, but more children may
>                                                           ^^^^^^^^^^^^
>   be available.
>   ^^^^^^^^^^^^^
> 
>   The @samp{numchild} field in other varobj responses is generally not
>   valid for a dynamic varobj -- it will show the number of children that
>   @value{GDBN} knows about, but because dynamic varobjs lazily
>   instantiate their children, this will not reflect the number of
>   children which may be available.
>   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

No, that's definitely not the same.  Here, the text just says that not
all children are shown, and "available" is used in its usual meaning.

> "available children" means children, whose values are available, or
> value available children.  How about replacing "available children"
> with "value available children"?  Is it clear?

No, sorry.  "Children whose values are available" is not clear at all.

Can you explain to me what makes the value "available", or what
prevents it from becoming available?  Then I will suggest a suitable
wording.

>  The number of children of the varobj.  This number is not necessarily
>  reliable for a dynamic varobj.  Instead, you must examine the
> -@samp{has_more} attribute.
> +@samp{has_more} attribute.  If the @samp{--available-children-only}
> +option was specified, this number is not reliable either.
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"this number is not reliable for any varobj".

Please also make similar corrections in other places.

The rest of the patch is OK, so we are only left with describing what
are the "value available children".

Thanks.