[RFA/doco] Fix gdb.Field attributes documentation for enum types.

[RFA/doco] Fix gdb.Field attributes documentation for enum types.

[Joel Brobecker]

Hello,

The following patch ...

    | commit 14e75d8ea4fe9ed4dbf292ae4a9745e33e2ff353
    | Date:   Wed Apr 18 06:46:47 2012 +0000
    |
    |     gdb/
    |         PR symtab/7259:
    | [...]

... discussed under ...

    [PATCH] Allow 64-bit enum values
    http://www.sourceware.org/ml/gdb-patches/2012-03/msg00772.html

... introduced a change in the gdb.Fields API without documenting it:

    | I took a separate approach from the one I took in:
    |
    | http://sourceware.org/ml/gdb-patches/2012-02/msg00403.html
    |
    | and removed the overloaded meaning of the bitpos location variable to
    | fix PR symtab/7259. In the following patch, I introduce a separate
    | field_location union member 'enumval' which can accept LONGEST and
    | hence expand enum values to 64-bit signed values. With this change,
    | bitpos now only is used for (non-negative) offsets into structures,
    | since the other overload of bitpos (range bounds) were already
    | separated into struct range_bound.

This patch updates the documentation to reflect that change.

gdb/doc/ChangeLog:

        * gdb.texinfo (Types In Python): Fix the documentation of
        attribute "bitpos" in class gdb.Field for enum types.  Add
        documentation for attribute "enumval" in that same class.

Tested on x86_linux. OK to check in?

Thanks,
-- 
Joel

---
 gdb/doc/gdb.texinfo | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 29f1cfc..cb0452f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24350,10 +24350,13 @@ into one of these categories, an empty sequence will be returned.
 Each field is a @code{gdb.Field} object, with some pre-defined attributes:
 @table @code
 @item bitpos
-This attribute is not available for @code{static} fields (as in
-C@t{++} or Java).  For non-@code{static} fields, the value is the bit
-position of the field.  For @code{enum} fields, the value is the
-enumeration member's integer representation.
+This attribute is not available for @code{enum} or @code{static}
+(as in C@t{++} or Java) fields.  The value is the bit position of
+the field.
+
+@item enumval
+This attribute is only available for @code{enum} fields, and its value
+is the enumeration member's integer representation.
 
 @item name
 The name of the field, or @code{None} for anonymous fields.
-- 
1.8.3.2

Re: [RFA/doco] Fix gdb.Field attributes documentation for enum types.

[Eli Zaretskii]

> From: Joel Brobecker <brobecker@adacore.com>
> Date: Mon, 23 Dec 2013 11:23:06 +0400
> 
> gdb/doc/ChangeLog:
> 
>         * gdb.texinfo (Types In Python): Fix the documentation of
>         attribute "bitpos" in class gdb.Field for enum types.  Add
>         documentation for attribute "enumval" in that same class.
> 
> Tested on x86_linux. OK to check in?

I guess so, although I'm not sure the reader will always understand
the exact meaning of "bit position of the field".  Maybe we should
explain some more?

Thanks.

Re: [RFA/doco] Fix gdb.Field attributes documentation for enum types.

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 733 bytes --]

> > gdb/doc/ChangeLog:
> > 
> >         * gdb.texinfo (Types In Python): Fix the documentation of
> >         attribute "bitpos" in class gdb.Field for enum types.  Add
> >         documentation for attribute "enumval" in that same class.
> > 
> > Tested on x86_linux. OK to check in?
> 
> I guess so, although I'm not sure the reader will always understand
> the exact meaning of "bit position of the field".  Maybe we should
> explain some more?

This is independent from the change I was making, but true, so
attached is a patch that tries to help. In the meantime, the patch
above is now in.

gdb/doc/ChangeLog:

        * gdb.texinfo (Types In Python): Clarify the documentation
        of attribute gdb.Field.bitpos.

-- 
Joel

[-- Attachment #2: 0001-Clarify-documentation-of-the-gdb.Field.bitpos-attrib.patch --]
[-- Type: text/x-diff, Size: 1068 bytes --]

From 616c57df75b3e0f3f943f5d13ac2f3cb9ac28c17 Mon Sep 17 00:00:00 2001
From: Joel Brobecker <brobecker@adacore.com>
Date: Sat, 28 Dec 2013 07:24:36 +0400
Subject: [PATCH] Clarify documentation of the gdb.Field.bitpos attribute

gdb/doc/ChangeLog:

        * gdb.texinfo (Types In Python): Clarify the documentation
        of attribute gdb.Field.bitpos.
---
 gdb/doc/gdb.texinfo | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 3fa0999..a60e6cf 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -24338,8 +24338,8 @@ 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}
-(as in C@t{++} or Java) fields.  The value is the bit position of
-the field.
+(as in C@t{++} or Java) fields.  The value is the position, counting
+in bits, from the start of the containing type.
 
 @item enumval
 This attribute is only available for @code{enum} fields, and its value
-- 
1.8.3.2

Re: [RFA/doco] Fix gdb.Field attributes documentation for enum types.

[Eli Zaretskii]

> Date: Sat, 28 Dec 2013 07:30:03 +0400
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: gdb-patches@sourceware.org
> 
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -24338,8 +24338,8 @@ 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}
> -(as in C@t{++} or Java) fields.  The value is the bit position of
> -the field.
> +(as in C@t{++} or Java) fields.  The value is the position, counting
> +in bits, from the start of the containing type.

Thanks, this is clear.

I'm curious: why are the bit units useful?  Field offsets are
generally counted in bytes, not bits.

Re: [RFA/doco] Fix gdb.Field attributes documentation for enum types.

[Joel Brobecker]

> >  @table @code
> >  @item bitpos
> >  This attribute is not available for @code{enum} or @code{static}
> > -(as in C@t{++} or Java) fields.  The value is the bit position of
> > -the field.
> > +(as in C@t{++} or Java) fields.  The value is the position, counting
> > +in bits, from the start of the containing type.
> 
> Thanks, this is clear.

Thanks. I just pushed the commit.

> I'm curious: why are the bit units useful?  Field offsets are
> generally counted in bytes, not bits.

It's normally true that fields are byte-aligned. But the containing
structures can also be packed, in which case the fields no longer
start at byte offsets. You need bit-precision to determine their
location. Some example in the GDB code bases are, I think, struct
symbol, where some of the fields are packed together to fit within
the same word, without regard to byte boundaries (avoiding unused
"holes").

-- 
Joel