[RFA/doco] set varsize-limit: New GDB setting for maximum dynamic object size

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>
> Date: Thu, 22 Feb 2018 10:21:13 -0500
> 
> +* New commands
> +
> +set|show varsize-limit
> +  This new setting allows the user to control the maximum size of Ada
> +  objects being printing when those objects have a dynamic type,
                   ^^^^^^^^
"printed", I guess?

> +  add_setshow_uinteger_cmd ("varsize-limit", class_support,
> +			    &varsize_limit, _("\
> +Set the maximum number of bytes allowed in a dynamic-sized object."), _("\
> +Show the maximum number of bytes allowed in a dynamic-sized object."), _("\
> +Attempts to access an object whose size is not a compile-time constant\n\
> +and exceeds this limit will cause an error."),

This is okay, but I wonder if "varsize" is a good name.  The
explanatory text you've written doesn't talk of any "variables".

> +@item set varsize-limit @var{size}
> +Limit the size of the types of objects to @var{size} bytes when those
> +sizes are computed from run-time quantities.

Is this only for printing, or is this more general?

in any case, "limit the size of types of objects" is ambiguous (the
"types" part confuses things), and doesn't really tell what does this
limit.  If it's only about printing, then let's say "don't print
objects whose size exceeds ...".  If it isn't limited to printing, how
about "don't attempt to evaluate objects ...".

>                                                When this limit is set
> +to @code{unlimited}, there is no limit.

I'd rephrase

  Setting @var{size} to @code{unlimited} removes the size limitations.

> +The purpose of having such a limit is to prevent @value{GDBN} from
> +trying to grab enormous chunks of virtual memory when asked to evaluate
> +a quantity whose bounds have been corrupted or have not yet been fully
> +initialized.  The limit applies to the results of some subexpressions
> +as well as to complete expressions.  For example, an expression denoting
> +a simple integer component, such as @code{x.y.z}, may fail if the size of
> +@var{x.y} is dynamic and exceeds @var{size}.  On the other hand,
> +@value{GDBN} is sometimes clever; the expression @code{A(i)}, where
> +@var{A} is an array variable with non-constant size, will generally
> +succeed regardless of the bounds on @var{A}, as long as the component
> +size is less than @var{size}.

All of the symbols except "size" should have the @code markup here,
not @var.

The documentation parts are okay with these nits fixed.

Thanks.