gdb: update Type.fields doc based on actual GDB behavior

I noticed two errors in the Type.fields documentation:

1. It is possible to call `fields` on an array type, in which case it
   returns one field representing the array's range.  It is not
   mentioned.

2. When calling `fields` on a type that doesn't have fields (by nature,
   like an int), GDB raises a TypeError.  It does not return an empty
   sequence, as currently documented.

Fix these, and change the text into a bullet list.  I find it easier to
read than one big paragraph.

The first issue is already tested in gdb.python/py-type.exp, but the
second one doesn't seem tested.  Add a test in gdb.python/py-type.exp
for it.

gdb/doc/ChangeLog:

	* python.texi (Types In Python): Re-organize Type.fields doc.
	Mention handling of array types.  Correct doc for when calling
	the method on another type.

gdb/testsuite/ChangeLog:

	* gdb.python/py-type.exp (test_fields): Test calling fields on
	an int type.

Change-Id: I11c688177504cb070b81a4446ac91dec50b56a22

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index d801d76dcebbb9ca35521a985f756266b5226b8d..ec961d232d1c890b2047d4bae16c1d57ce936c5d 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2021-05-04  Simon Marchi  <simon.marchi@polymtl.ca>
+
+       * python.texi (Types In Python): Re-organize Type.fields doc.
+       Mention handling of array types.  Correct doc for when calling
+       the method on another type.
+
 2021-04-28  Andrew Burgess  <andrew.burgess@embecosm.com>
 
        * gdb.texinfo (Initialization Files): Use @env when referencing

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 20d65742964dfd5e2ae07c25b2c1598960d5e7b3..482d328de44a93b91afa3bb8aa9ffde3a85d3aca 100644 (file)
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1163,12 +1163,32 @@ there is no associated objfile.
 The following methods are provided:
 
 @defun Type.fields ()
-For structure and union types, this method returns the fields.  Range
-types have two fields, the minimum and maximum values.  Enum types
-have one field per enum constant.  Function and method types have one
-field per parameter.  The base types of C@t{++} classes are also
-represented as fields.  If the type has no fields, or does not fit
-into one of these categories, an empty sequence will be returned.
+
+Return the fields of this type.  The behavior depends on the type code:
+
+@itemize @bullet
+
+@item
+For structure and union types, this method returns the fields.
+
+@item
+Range types have two fields, the minimum and maximum values.
+
+@item
+Enum types have one field per enum constant.
+
+@item
+Function and method types have one field per parameter.  The base types of
+C@t{++} classes are also represented as fields.
+
+@item
+Array types have one field representing the array's range.
+
+@item
+If the type does not fit into one of these categories, a @code{TypeError}
+is raised.
+
+@end itemize
 
 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
 @table @code

diff --git a/gdb/testsuite/ChangeLog b/gdb/testsuite/ChangeLog
index 32eba3663a74caa30f53f11a23a38b4daff99b23..326ba47961f8d65acda18b14fbbe85d59a395ce9 100644 (file)
--- a/gdb/testsuite/ChangeLog
+++ b/gdb/testsuite/ChangeLog
@@ -1,3 +1,8 @@
+2021-05-04  Simon Marchi  <simon.marchi@polymtl.ca>
+
+       * gdb.python/py-type.exp (test_fields): Test calling fields on
+       an int type.
+
 2021-05-04  Simon Marchi  <simon.marchi@efficios.com>
 
        * gdb.python/flexible-array-member.exp: Adjust expected range

diff --git a/gdb/testsuite/gdb.python/py-type.exp b/gdb/testsuite/gdb.python/py-type.exp
index 5c0c4f5706fc974e8a3c456f29c87f1f30e16316..733b25d3210688c2a718b00c8eaa1cd4a8754fbe 100644 (file)
--- a/gdb/testsuite/gdb.python/py-type.exp
+++ b/gdb/testsuite/gdb.python/py-type.exp
@@ -175,6 +175,9 @@ proc test_fields {lang} {
     gdb_test "python print (len (gdb.parse_and_eval ('a_function').type.fields ()))" "2"
     gdb_test "python print (gdb.parse_and_eval ('a_function').type.fields ()\[0\].type)" "int"
     gdb_test "python print (gdb.parse_and_eval ('a_function').type.fields ()\[1\].type)" "char"
+
+    # Test calling `fields` on a non-aggregate type.
+    gdb_test "python gdb.lookup_type('int').fields()" "TypeError: Type is not a structure, union, enum, or function type.*"
   }
 }