Expand dynamic type documentation

Message ID 20200424203911.26599-1-tromey@adacore.com
State New
Headers show
Series
  • Expand dynamic type documentation
Related show

Commit Message

Tom Tromey April 24, 2020, 8:39 p.m.
This expands the Python dynamic type documentation, as suggested by
Christian.

gdb/doc/ChangeLog
2020-04-24  Tom Tromey  <tromey@adacore.com>

	* python.texi (Types In Python): Mention missing fields.  Add
	dynamic type example.
---
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/python.texi | 22 ++++++++++++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

-- 
2.21.1

Comments

Eli Zaretskii April 25, 2020, 5:59 a.m. | #1
> From: Tom Tromey <tromey@adacore.com>

> Date: Fri, 24 Apr 2020 14:39:11 -0600

> Cc: Tom Tromey <tromey@adacore.com>

> 

> This expands the Python dynamic type documentation, as suggested by

> Christian.

> 

> gdb/doc/ChangeLog

> 2020-04-24  Tom Tromey  <tromey@adacore.com>

> 

> 	* python.texi (Types In Python): Mention missing fields.  Add

> 	dynamic type example.


Fine with me, with one minor comment:

> +Here, at least conceptually (whether your compiler actually does this

> +is a separate issue), examining @code{gdb.lookup_symbol("array", ...).type}


This long @code{..} expression is likely to be split between lines; to
prevent that, I suggest to wrap it in @w{..}.

Thanks.
Tom Tromey April 27, 2020, 2:28 p.m. | #2
>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:


>> +Here, at least conceptually (whether your compiler actually does this

>> +is a separate issue), examining @code{gdb.lookup_symbol("array", ...).type}


Eli> This long @code{..} expression is likely to be split between lines; to
Eli> prevent that, I suggest to wrap it in @w{..}.

Thanks, I'm checking it in with this change.

Tom

Patch

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index cfa813128ce..faddf6a1ed3 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1071,7 +1071,24 @@  The type code for this type.  The type code will be one of the
 @defvar Type.dynamic
 A boolean indicating whether this type is dynamic.  In some
 situations, such as Rust @code{enum} types or Ada variant records, the
-concrete type of a value may vary depending on its contents.
+concrete type of a value may vary depending on its contents.  That is,
+the declared type of a variable, or the type returned by
+@code{gdb.lookup_type} may be dynamic; while the type of the
+variable's value will be a concrete instance of that dynamic type.
+
+For example, consider this code:
+@smallexample
+int n;
+int array[n];
+@end smallexample
+
+Here, at least conceptually (whether your compiler actually does this
+is a separate issue), examining @code{gdb.lookup_symbol("array", ...).type}
+could yield a @code{gdb.Type} which reports a size of @code{None}.
+This is the dynamic type.
+
+However, examining @code{gdb.parse_and_eval("array").type} would yield
+a concrete type, whose length would be known.
 @end defvar
 
 @defvar Type.name
@@ -1116,7 +1133,8 @@  This attribute is not available for @code{enum} or @code{static}
 (as in C@t{++}) fields.  The value is the position, counting
 in bits, from the start of the containing type.  Note that, in a
 dynamic type, the position of a field may not be constant.  In this
-case, the value will be @code{None}.
+case, the value will be @code{None}.  Also, a dynamic type may have
+fields that do not appear in a corresponding concrete type.
 
 @item enumval
 This attribute is only available for @code{enum} fields, and its value