bpo-29753: improve documentation PyCField_FromDesc relating packed bitfields

Signed-off-by: Filipe Laíns <[email protected]>

Author: FFY00

Modules/_ctypes/cfield.c

@@ -73,7 +73,9 @@ PyCField_FromDesc(PyObject *desc, Py_ssize_t index,
     }
 
 #ifndef MS_WIN32
-    if (pack && bitsize) { /* packed bitfield */
+    /* if we have a packed bitfield, calculate the minimum number of bytes we
+    need to fit it. otherwise use the specified size. */
+    if (pack && bitsize) {
         size = (bitsize - 1) / 8 + 1;
     } else
 #endif
@@ -97,6 +99,8 @@ PyCField_FromDesc(PyObject *desc, Py_ssize_t index,
     } else if (bitsize /* this is a bitfield request */
         && *pfield_size /* we have a bitfield open */
         && dict->size * 8 >= *pfield_size
+        /* if this is a packed bitfield, always expand it.
+           otherwise calculate if we need to expand it. */
         && (((*pbitofs + bitsize) <= dict->size * 8) || pack)) {
         /* expand bit field */
         fieldtype = EXPAND_BITFIELD;
@@ -105,6 +109,8 @@ PyCField_FromDesc(PyObject *desc, Py_ssize_t index,
         /* start new bitfield */
         fieldtype = NEW_BITFIELD;
         *pbitofs = 0;
+        /* use our calculated size (size) instead of type size (dict->size),
+           which can be different for packed bitfields */
         *pfield_size = size * 8;
     } else {
         /* not a bit field */
@@ -177,6 +183,9 @@ PyCField_FromDesc(PyObject *desc, Py_ssize_t index,
         break;
 
     case EXPAND_BITFIELD:
+        /* increase the size if it is a packed bitfield.
+           EXPAND_BITFIELD should not be selected for non-packed fields if the
+           current size isn't already enough. */
         if (pack)
             size = (*pbitofs + bitsize - 1) / 8 + 1;