bpo-44072: fix Complex, Integral docs for ** (GH-25986)

In numbers module docstrings and docs.

Author: roryyorke

Doc/library/numbers.rst

@@ -27,8 +27,8 @@ The numeric tower
  Subclasses of this type describe complex numbers and include the operations
  that work on the built-in :class:`complex` type. These are: conversions to
  :class:`complex` and :class:`bool`, :attr:`.real`, :attr:`.imag`, ``+``,
- ``-``, ``*``, ``/``, :func:`abs`, :meth:`conjugate`, ``==``, and ``!=``. All
- except ``-`` and ``!=`` are abstract.
+ ``-``, ``*``, ``/``, ``**``, :func:`abs`, :meth:`conjugate`, ``==``, and
+ ``!=``. All except ``-`` and ``!=`` are abstract.
 
  .. attribute:: real
 
@@ -76,8 +76,9 @@ The numeric tower
 
  Subtypes :class:`Rational` and adds a conversion to :class:`int`. Provides
  defaults for :func:`float`, :attr:`~Rational.numerator`, and
- :attr:`~Rational.denominator`. Adds abstract methods for ``**`` and
- bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``.
+ :attr:`~Rational.denominator`. Adds abstract methods for :func:`pow` with
+ modulus and bit-string operations: ``<<``, ``>>``, ``&``, ``^``, ``|``,
+ ``~``.
 
 
 Notes for type implementors

Lib/numbers.py

@@ -33,7 +33,7 @@ class Complex(Number):
  """Complex defines the operations that work on the builtin complex type.
 
  In short, those are: a conversion to complex, .real, .imag, +, -,
- *, /, abs(), .conjugate, ==, and !=.
+ *, /, **, abs(), .conjugate, ==, and !=.
 
  If it is given heterogeneous arguments, and doesn't have special
  knowledge about them, it should fall back to the builtin complex
@@ -292,7 +292,11 @@ def __float__(self):
 
 
 class Integral(Rational):
- """Integral adds a conversion to int and the bit-string operations."""
+ """Integral adds methods that work on integral numbers.
+
+ In short, these are conversion to int, pow with modulus, and the
+ bit-string operations.
+ """
 
  __slots__ = ()
 

Misc/NEWS.d/next/Documentation/2021-05-08-09-48-05.bpo-44072.fb2x5I.rst

@@ -0,0 +1,2 @@
+Correct where in the numeric ABC hierarchy ``**`` support is added, i.e., in
+numbers.Complex, not numbers.Integral.