Re: Ping: frozen variable objects

[Nick Roberts <nickrob@snap.net.nz>]

 > >  The range of values for fields with specified values, e.g.,
 > > -@code{in_scope} (@pxref{-var-update}) may be extended.
 > > +@code{in_scope} (@pxref{-var-update-fields}) may be extended.
 > 
 > Doesn't that read a little odd to you?  I'd think '-var-update fields'
 > at least.

Also the name that is displayed shouldn't change, so pxref needs to be
called with two arguments:


@code{in_scope} (@pxref{-var-update fields, -var-update}) may be extended.

and

@anchor{-var-update fields}
The field in_scope may take three values:

Here are some other observations about the documentation:

frozenness (not a common word) has two ns.

In the description for -var-set-frozen:

  parameter should be either `1' to make the variable frozen or `0' to
  make it unfozen.  If a variable object is frozen, then neither itself,
          ^^^^^^^

In the description for -var-update:

  If `*' is used as the variable object names, all existing variable objects
  are updated.

Since frozen variables aren't updated implicitly, I would move some
of the description of them from -var-set-frozen to here.

  @c The format of field's content e.g type prefix, may change so parse it
   @c   at your own risk.  Yes, in general?
  @@ -19536,7 +19536,10 @@ that corresponds to a composite type, su
   a number of child variable objects, for example corresponding to each
   element of a structure.  A child variable object can itself have 
   children, recursively.  Recursion ends when we reach 
  -leaf variable objects, which always have built-in types.
  +leaf variable objects, which always have built-in types.  Child variable
  +objects are created only by explicit request, so if a frontend 
  +is not interested in the children of a particular variable object, no
  +child will be created.
 
   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
  @@ -19548,7 +19551,19 @@ A frontend does not need to read the val
   the program stops.  Instead, MI provides an update command that lists all
   variable objects whose values has changed since the last update
   operation.  This considerably reduces the amount of data that must
  -be transferred to the frontend.
  +be transferred to the frontend.  As noted above, children variable
  +objects are created on demand, and only leaf variable objects have a
  +real value.  As result, gdb will read target memory only for leaf
  +variables that frontend has created.

Why not just:

  @c The format of field's content e.g type prefix, may change so parse it
   @c   at your own risk.  Yes, in general?
  @@ -19536,7 +19536,10 @@ that corresponds to a composite type, su
   a number of child variable objects, for example corresponding to each
   element of a structure.  A child variable object can itself have 
   children, recursively.  Recursion ends when we reach 
  -leaf variable objects, which always have built-in types.
  +leaf variable objects, which always have built-in types.  Child variable
  +objects are created only by explicit request, so if a frontend 
  +is not interested in the children of a particular variable object, no
  +child will be created.   As result, gdb will read target memory only for
  +leaf variables that frontend has created.


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