gh-113706: Update comment about long int representation (#113707)

1 files changed, 21 insertions, 10 deletions

diff --git a/Include/cpython/longintrepr.h b/Include/cpython/longintrepr.h
index f5ccbb7..f037c7b 100644
--- a/Include/cpython/longintrepr.h
+++ b/Include/cpython/longintrepr.h
@@ -62,21 +62,32 @@ typedef long stwodigits; /* signed variant of twodigits */
 #define PyLong_MASK     ((digit)(PyLong_BASE - 1))
 
 /* Long integer representation.
+
+   Long integers are made up of a number of 30- or 15-bit digits, depending on
+   the platform. The number of digits (ndigits) is stored in the high bits of
+   the lv_tag field (lvtag >> _PyLong_NON_SIZE_BITS).
+
    The absolute value of a number is equal to
-        SUM(for i=0 through abs(ob_size)-1) ob_digit[i] * 2**(SHIFT*i)
-   Negative numbers are represented with ob_size < 0;
-   zero is represented by ob_size == 0.
-   In a normalized number, ob_digit[abs(ob_size)-1] (the most significant
+        SUM(for i=0 through ndigits-1) ob_digit[i] * 2**(PyLong_SHIFT*i)
+
+   The sign of the value is stored in the lower 2 bits of lv_tag.
+
+    - 0: Positive
+    - 1: Zero
+    - 2: Negative
+
+   The third lowest bit of lv_tag is reserved for an immortality flag, but is
+   not currently used.
+
+   In a normalized number, ob_digit[ndigits-1] (the most significant
    digit) is never zero.  Also, in all cases, for all valid i,
-        0 <= ob_digit[i] <= MASK.
+        0 <= ob_digit[i] <= PyLong_MASK.
+
    The allocation function takes care of allocating extra memory
-   so that ob_digit[0] ... ob_digit[abs(ob_size)-1] are actually available.
+   so that ob_digit[0] ... ob_digit[ndigits-1] are actually available.
    We always allocate memory for at least one digit, so accessing ob_digit[0]
-   is always safe. However, in the case ob_size == 0, the contents of
+   is always safe. However, in the case ndigits == 0, the contents of
    ob_digit[0] may be undefined.
-
-   CAUTION:  Generic code manipulating subtypes of PyVarObject has to
-   aware that ints abuse  ob_size's sign bit.
 */
 
 typedef struct _PyLongValue {