[PATCH] Minor doc fix for Python Type.fields

[PATCH] Minor doc fix for Python Type.fields

[Tom Tromey]

This changes the Python Type.fields documentation in a few minor ways:

* Documents that a new sequence is always returned I've intentionally
  not mentioned that it is currently a list, in case we want to change
  to a tuple someday.

* Move the C++ base class note to the bullet about structure types,
  where it makes more sense.

* Added a blank line before the table to make the info page easier to
  read.
---
 gdb/doc/python.texi | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 13ffde253d3..44a94aa34c9 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1501,19 +1501,20 @@ The following methods are provided:
 
 @defun Type.fields ()
 
-Return the fields of this type.  The behavior depends on the type code:
+Return a new sequence of 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.
+For structure and union types, this method returns the fields.  The
+base types of C@t{++} classes are also represented as fields.
 
 @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.
+Function and method types have one field per parameter.
 
 @item
 Array types have one field representing the array's range.
@@ -1525,6 +1526,7 @@ is raised.
 @end itemize
 
 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
+
 @table @code
 @item bitpos
 This attribute is not available for @code{enum} or @code{static}

base-commit: ce106639c2019494833b5a8388d205ba96e7b217
-- 
2.51.0

Re: [PATCH] Minor doc fix for Python Type.fields

[Paul Koning]

> On Nov 5, 2025, at 1:10 PM, Tom Tromey <tromey@adacore.com> wrote:
> 
> This changes the Python Type.fields documentation in a few minor ways:
> 
> * Documents that a new sequence is always returned I've intentionally
>  not mentioned that it is currently a list, in case we want to change
>  to a tuple someday.

Why is it important to say that a new sequence is returned?  It seems to me that someday we may want to return the same sequence if thisis called multiple times.


	paul

Re: [PATCH] Minor doc fix for Python Type.fields

[Tom Tromey]

>> * Documents that a new sequence is always returned I've intentionally
>> not mentioned that it is currently a list, in case we want to change
>> to a tuple someday.

Paul> Why is it important to say that a new sequence is returned?  It
Paul> seems to me that someday we may want to return the same sequence
Paul> if thisis called multiple times.

Yeah, I guess it isn't needed always.
Like if gdb ever returned a tuple, it could be memoized.
I wonder if Python has some idiomatic way to say "this is guaranteed to
either return a tuple or a new list"

Or if we should just write 'new list' and commit gdb to not memoizing.

Tom

Re: [PATCH] Minor doc fix for Python Type.fields

[Paul Koning]

> On Nov 5, 2025, at 2:05 PM, Tom Tromey <tromey@adacore.com> wrote:
> 
>>> * Documents that a new sequence is always returned I've intentionally
>>> not mentioned that it is currently a list, in case we want to change
>>> to a tuple someday.
> 
> Paul> Why is it important to say that a new sequence is returned?  It
> Paul> seems to me that someday we may want to return the same sequence
> Paul> if thisis called multiple times.
> 
> Yeah, I guess it isn't needed always.
> Like if gdb ever returned a tuple, it could be memoized.
> I wonder if Python has some idiomatic way to say "this is guaranteed to
> either return a tuple or a new list"
> 
> Or if we should just write 'new list' and commit gdb to not memoizing.
> 
> Tom

My point is slightly different.  No matter what sequence type is returned, for a given Type object the value of the sequence returned would be the same if you call that method twice, right?  So if I do:

	a = sometype.fields()
	b = sometype.fields()

then a == b.  The statement "new sequence" promises that "a is not b", i.e., a and b are not the same object.  But I see no reason why that is a useful property, and whether a and b are lists or tuples, it would be reasonable for "a is b" to hold.  (Reasonable though not required.)

	paul

Re: [PATCH] Minor doc fix for Python Type.fields

[Tom Tromey]

Paul> My point is slightly different.  No matter what sequence type is
Paul> returned, for a given Type object the value of the sequence
Paul> returned would be the same if you call that method twice, right?

If gdb returns a memoized list, then modifications to the list will
affect other calls.  But, that would be undesirable.

Tom

Re: [PATCH] Minor doc fix for Python Type.fields

[Paul Koning]

> On Nov 5, 2025, at 2:27 PM, Tom Tromey <tromey@adacore.com> wrote:
> 
> Paul> My point is slightly different.  No matter what sequence type is
> Paul> returned, for a given Type object the value of the sequence
> Paul> returned would be the same if you call that method twice, right?
> 
> If gdb returns a memoized list, then modifications to the list will
> affect other calls.  But, that would be undesirable.
> 
> Tom

Yes, I wasn't thinking of someone modifying that value.  I don't know a short expression for "tuple or new list".

Would it be hard to make it a tuple and not worry for now if it's memoized or not?  That way you get the immutable property which makes sense to have.

	paul

Re: [PATCH] Minor doc fix for Python Type.fields

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Wed,  5 Nov 2025 11:10:59 -0700
> 
> This changes the Python Type.fields documentation in a few minor ways:
> 
> * Documents that a new sequence is always returned I've intentionally
>   not mentioned that it is currently a list, in case we want to change
>   to a tuple someday.
> 
> * Move the C++ base class note to the bullet about structure types,
>   where it makes more sense.
> 
> * Added a blank line before the table to make the info page easier to
>   read.
> ---
>  gdb/doc/python.texi | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)

This is okay, thanks.

Approved-By: Eli Zaretskii <eliz@gnu.org>