[docs] [issue12880] ctypes: clearly document how structure bit fields are allocated

[Meador Inge]

Meador Inge <meadori at gmail.com> added the comment:

On Fri, Sep 30, 2011 at 12:19 PM, Vlad Riscutia <report at bugs.python.org> wrote:

> I believe this is the better thing to do rather than detailing how GCC and MSVC allocated their bitfields because that would just
> encourage people to use this feature incorrectly.

So clearly documenting how a feature works will cause people to use
the feature incorrectly?  I think not.  In any case, I agree that
documenting the low-level specifics of each compiler's algorithm is too much.

> Most bugs opened on bit fields are because people are toying with the underlying buffer and get other results than what they expect.

The issues that I have looked at (issue6069, issue11920, and
issue11920) all involve fundamental misunderstandings of *how* the
structure layout is determined.  I don't know if I would generalize
these misunderstanding as "toying with the underlying buffer".  Some
times people need to know the exact layout for proper C interop.  In
some of the bugs reported folks are casting buffers in an attempt
to discover the structure layout since it is not clearly documented.

The general content of your patch seems reasonable.  I will provide
more specific comments shortly.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12880>
_______________________________________