[DOC] Tweaks for Integer#**

1 files changed, 42 insertions, 11 deletions

diff --git a/numeric.c b/numeric.c
index a9e5fa7866..a2c91d87a5 100644
--- a/numeric.c
+++ b/numeric.c
@@ -4592,17 +4592,48 @@ fix_pow(VALUE x, VALUE y)
 
 /*
  *  call-seq:
- *    self ** numeric -> numeric_result
- *
- *  Raises +self+ to the power of +numeric+:
- *
- *    2 ** 3              # => 8
- *    2 ** -3             # => (1/8)
- *    -2 ** 3             # => -8
- *    -2 ** -3            # => (-1/8)
- *    2 ** 3.3            # => 9.849155306759329
- *    2 ** Rational(3, 1) # => (8/1)
- *    2 ** Complex(3, 0)  # => (8+0i)
+ *    self ** exponent -> numeric
+ *
+ *  Returns the value of base +self+ raised to the power +exponent+;
+ *  see {Exponentiation}[https://en.wikipedia.org/wiki/Exponentiation]:
+ *
+ *    # Result for non-negative Integer exponent is Integer.
+ *    2 ** 0   # => 1
+ *    2 ** 1   # => 2
+ *    2 ** 2   # => 4
+ *    2 ** 3   # => 8
+ *    -2 ** 3  # => -8
+ *    # Result for negative Integer exponent is Rational, not Float.
+ *    2 ** -3  # => (1/8)
+ *    -2 ** -3 # => (-1/8)
+ *
+ *    # Result for Float exponent is Float.
+ *    2 ** 0.0   # => 1.0
+ *    2 ** 1.0   # => 2.0
+ *    2 ** 2.0   # => 4.0
+ *    2 ** 3.0   # => 8.0
+ *    -2 ** 3.0  # => -8.0
+ *    2 ** -3.0  # => 0.125
+ *    -2 ** -3.0 # => -0.125
+ *
+ *    # Result for non-negative Complex exponent is Complex with Integer parts.
+ *    2 ** Complex(0, 0)   # => (1+0i)
+ *    2 ** Complex(1, 0)   # => (2+0i)
+ *    2 ** Complex(2, 0)   # => (4+0i)
+ *    2 ** Complex(3, 0)   # => (8+0i)
+ *    -2 ** Complex(3, 0) # => (-8+0i)
+ *    # Result for negative Complex exponent is Complex with Rational parts.
+ *    2 ** Complex(-3, 0)  # => ((1/8)+(0/1)*i)
+ *    -2 ** Complex(-3, 0) # => ((-1/8)+(0/1)*i)
+ *
+ *    # Result for Rational exponent is Rational.
+ *    2 ** Rational(0, 1)   # => (1/1)
+ *    2 ** Rational(1, 1)   # => (2/1)
+ *    2 ** Rational(2, 1)   # => (4/1)
+ *    2 ** Rational(3, 1)   # => (8/1)
+ *    -2 ** Rational(3, 1)  # => (-8/1)
+ *    2 ** Rational(-3, 1)  # => (1/8)
+ *    -2 ** Rational(-3, 1) # => (-1/8)
  *
  */
 VALUE