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

[Eli Zaretskii <eliz@gnu.org>]

> From: Yao Qi <yao@codesourcery.com>
> Date: Fri, 14 Feb 2014 16:44:31 +0800
> 
> gdb/doc:
> 
> 2014-02-14  Pedro Alves  <pedro@codesourcery.com>
> 	    Yao Qi  <yao@codesourcery.com>
> 
> 	* gdb.texinfo (GDB/MI Variable Objects): Update doc of MI
> 	commands "-var-create", "-var-info-num-children" and
> 	"-var-list-children".
> 	(GDB/MI Support Commands): Document the new
> 	"available-children-only" entry in the output of the
> 	"-list-features" command.

Thanks.  I have a few comments:

> +  ** The commands -var-create, -var-info-num-children and
> +     -var-list-children now accept an option
> +     "--available-children-only".  When used, only the available
> +     children are displayed.  Support for this feature can be verified
> +     using the "-list-features" command, which should contain
> +     "available-children-only".

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?

> +If the @samp{--available-children-only} option is specified, then only
> +available or collected children of the varobj are considered.

Again, without explaining what "available children" means, or maybe
which children might be "unavailable", this description just repeats
the name of the option.

>  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.
> +reliable for a dynamic varobj or for a non-dynamic varobj if the
> +@samp{--available-children-only} option was specified.

When --available-children-only is specified, isn't it true that this
number is unreliable for _any_ varobj?  If so, please rephrase to make
that explicit.

> -For a dynamic varobj, this indicates whether there appear to be any
> -children available.  For a non-dynamic varobj, this will be 0.
> +For a dynamic varobj, or for a non-dynamic varobj when the
> +@samp{--available-children-only} option is specified, this indicates
> +whether there appear to be more children that haven't been listed yet,
> +which can be listed with a following @code{-var-list-children}
> +command.  For the other cases, this will be 0.

Same here.

> +Note that this number is not completely reliable for a dynamic varobj
> +or for a non-dynamic varobj that is listing only available or
> +collected children.  It will return the current number of children,
> +but more children may be available.

And here.

> +If for a given varobj, the presence of the
> +@samp{--available-children-only} option changes between invocations of
> +the @code{-var-create}, @code{-var-list-children} or
> +@code{-var-info-num-children} commands, the list of children is
> +reinitialized.

"Presence of the ... option changes" sounds awkward.  Does this
sentence say anything important?  IOW, does reinitialization of the
list of children have any user-visible effects?  If not, perhaps it is
better to delete it.  If you think this is needed, then I'd rephrase
like this:

 If you use any of the commands @code{-var-create},
 @code{-var-list-children}, or @code{-var-info-num-children} with the
 @samp{--available-children-only} option followed by any of these
 commands without that option, or vice versa, the list of children is
 reinitialized.

>  @smallexample
> - -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
> + -var-list-children
> +   [--available-children-only]
> +   [@var{print-values}] @var{name} [@var{from} @var{to}]
>  @end smallexample

Will the reader understand that this is one long line broken for
readability?  If not, perhaps you should tell that explicitly.

> +If the @samp{--available-children-only} option is specified, then only
> +available or collected children of the varobj are considered.

Once again, "available children" needs to be explained.

> +If for a given varobj, the presence of the
> +@samp{--available-children-only} option changes between invocations of
> +the @code{-var-create}, @code{-var-list-children} or
> +@code{-var-info-num-children} commands, the list of children is
> +reinitialized.

Same comment as above.

>  @item new_num_children
> -For a dynamic varobj, if the number of children changed, or if the
> -type changed, this will be the new number of children.
> +For a dynamic varobj, or non-dynamic varobj that had been created as
> +consequence of the @samp{--available-children-only} option to the
> +@code{-var-create}, @code{-var-list-children} or
> +@code{-var-info-num-children} commands, if the number of children
> +changed, or if the type changed, this will be the new number of
> +children.

This sentence is now too long and complicated to be clear.  Suggest to
break into 2 sentences.  E.g., leave the original sentence as is, and
then add something like

  Similarly for a non-dynamic varobj that was created as result of the
  @samp{--available-children-only} option ...