What's Here for Numeric and Comparable

7 files changed, 120 insertions, 12 deletions

diff --git a/array.c b/array.c
index a1e0c13659..3cb57a0872 100644
--- a/array.c
+++ b/array.c
@@ -8160,8 +8160,11 @@ rb_ary_deconstruct(VALUE ary)
  *
  *  == What's Here
  *
- *  First, what's elsewhere. \Array includes the module Enumerable,
- *  which provides dozens of additional methods.
+ *  First, what's elsewhere. \Class \Array:
+ *
+ *  - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ *  - Includes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here],
+ *    which provides dozens of additional methods.
  *
  *  Here, class \Array provides methods that are useful for:
  *
diff --git a/compar.c b/compar.c
index 04d4ff8c70..0de318525c 100644
--- a/compar.c
+++ b/compar.c
@@ -289,6 +289,22 @@ cmp_clamp(int argc, VALUE *argv, VALUE x)
  *     s4.between?(s3, s5)           #=> true
  *     [ s3, s2, s5, s4, s1 ].sort   #=> [Z, YY, XXX, WWWW, VVVVV]
  *
+ *  == What's Here
+ *
+ *  \Module \Comparable provides these methods, all of which use method <tt><=></tt>:
+ *
+ *  - {<}[#method-i-3C]:: Returns whether +self+ is less than the given object.
+ *  - {<=}[#method-i-3C-3D]:: Returns whether +self+ is less than or equal to
+ *                            the given object.
+ *  - {==}[#method-i-3D-3D]:: Returns whether +self+ is equal to the given object.
+ *  - {>}[#method-i-3E]:: Returns whether +self+ is greater than or equal to
+ *                        the given object.
+ *  - {>=}[#method-i-3E-3D]:: Returns whether +self+ is greater than the given object.
+ *  - #between? Returns +true+ if +self+ is between two given objects.
+ *  - #clamp:: For given objects +min+ and +max+, or range <tt>(min..max)</tt>, returns:
+ *    - +min+ if <tt>(self <=> min) < 0</tt>.
+ *    - +max+ if <tt>(self <=> max) > 0</tt>.
+ *    - +self+ otherwise.
  */
 
 void
diff --git a/file.c b/file.c
index 82d1029b7f..649dfcc428 100644
--- a/file.c
+++ b/file.c
@@ -6542,11 +6542,12 @@ const char ruby_null_device[] =
  *
  *  First, what's elsewhere. \Class \File:
  *
- *  - Inherits from class IO -- in particular, methods for creating,
- *    reading, and writing files.
- *  - Includes module FileTest.
+ *  - Inherits from {class IO}[IO.html#class-IO-label-What-27s+Here],
+ *    in particular, methods for creating, reading, and writing files
+ *  - Includes {module FileTest}[FileTest.html#module-FileTest-label-What-27s+Here].
+ *    which provides dozens of additional methods.
  *
- *  Here, Class \File provides methods that are useful for:
+ *  Here, class \File provides methods that are useful for:
  *
  *  - {Creating}[#class-File-label-Creating]
  *  - {Querying}[#class-File-label-Querying]
diff --git a/hash.c b/hash.c
index 375342a89a..ca80e7ea1d 100644
--- a/hash.c
+++ b/hash.c
@@ -6884,8 +6884,11 @@ env_dup(VALUE obj)
  *
  *  === What's Here
  *
- *  First, what's elsewhere. \Hash includes the module Enumerable,
- *  which provides dozens of additional methods.
+ *  First, what's elsewhere. \Class \Hash:
+ *
+ *  - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ *  - Includes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here],
+ *    which provides dozens of additional methods.
  *
  *  Here, class \Hash provides methods that are useful for:
  *
diff --git a/io.c b/io.c
index a0a5389c1b..d11f4076bb 100644
--- a/io.c
+++ b/io.c
@@ -13369,8 +13369,11 @@ set_LAST_READ_LINE(VALUE val, ID _x, VALUE *_y)
  *
  *  == What's Here
  *
- *  First, what's elsewhere. \Class \IO includes the module Enumerable,
- *  which provides dozens of additional methods.
+ *  First, what's elsewhere. \Class \IO:
+ *
+ *  - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ *  - Includes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here],
+ *    which provides dozens of additional methods.
  *
  *  Here, class \IO provides methods that are useful for:
  *
diff --git a/numeric.c b/numeric.c
index b1425cad02..c9dc24bcf1 100644
--- a/numeric.c
+++ b/numeric.c
@@ -5341,6 +5341,86 @@ rb_int_s_isqrt(VALUE self, VALUE num)
  *   tally = Tally.new('||')
  *   puts tally * 2            #=> "||||"
  *   puts tally > 1            #=> true
+ *
+ * == What's Here
+ *
+ * First, what's elsewhere. \Class \Numeric:
+ *
+ * - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ * - Includes {module Comparable}[Comparable.html#module-Comparable-label-What-27s+Here].
+ *
+ * Here, class \Numeric provides methods for:
+ *
+ * - {Querying}[#class-Numeric-label-Querying]
+ * - {Comparing}[#class-Numeric-label-Comparing]
+ * - {Converting}[#class-Numeric-label-Converting]
+ * - {Other}[#class-Numeric-label-Other]
+ *
+ * === Querying
+ *
+ * - #finite?:: Returns true unless +self+ is infinite or not a number.
+ * - #infinite?:: Returns -1, +nil+ or +1, depending on whether +self+
+ *                is <tt>-Infinity<tt>, finite, or <tt>+Infinity</tt>.
+ * - #integer?:: Returns whether +self+ is an integer.
+ * - #negative?:: Returns whether +self+ is negative.
+ * - #nonzero?:: Returns whether +self+ is not zero.
+ * - #positive?:: Returns whether +self+ is positive.
+ * - #real?:: Returns whether +self+ is a real value.
+ * - #zero?:: Returns whether +self+ is zero.
+ *
+ * === Comparing
+ *
+ * - {<=>}[#method-i-3C-3D-3E]:: Returns:
+ *   - -1 if  +self+ is less than the given value.
+ *   - 0 if +self+ is equal to the given value.
+ *   - 1 if +self is greater than the given value.
+ *   - +nil+ if +self+ and the given value are not comparable.
+ * - #eql?:: Returns whether +self+ and the given value have the same value and type.
+ *
+ * === Converting
+ *
+ * - #% (aliased as #modulo):: Returns the remainder of +self+ divided by the given value.
+ * - #-@:: Returns the value of +self+, negated.
+ * - #abs (aliased as #magnitude):: Returns the absolute value of +self+.
+ * - #abs2:: Returns the square of +self+.
+ * - #angle (aliased as #arg and #phase):: Returns 0 if +self+ is positive,
+ *                                         Math::PI otherwise.
+ * - #ceil:: Returns the smallest number greater than or equal to +self+,
+ *           to a given precision.
+ * - #coerce:: Returns array <tt>[coerced_self, coerced_other]</tt>
+ *             for the given other value.
+ * - #conj (aliased as #conjugate):: Returns the complex conjugate of +self+.
+ * - #denominator:: Returns the denominator (always positive)
+ *                  of the Rational representation of +self+.
+ * - #div:: Returns the value of +self+ divided by the given value
+ *          and converted to an integer.
+ * - #divmod:: Returns array <tt>[quotient, modulus]</tt> resulting
+ *             from dividing +self+ the given divisor.
+ * - #fdiv:: Returns the Float result of dividing +self+ by the given divisor.
+ * - #floor:: Returns the largest number less than or equal to +self+,
+ *            to a given precision.
+ * - #i:: Returns the Complex object <tt>Complex(0, self)</tt>.
+ *        the given value.
+ * - #imaginary (aliased as #imag):: Returns the imaginary part of the +self+.
+ * - #numerator:: Returns the numerator of the Rational representation of +self+;
+ *                has the same sign as +self+.
+ * - #polar:: Returns the array <tt>[self.abs, self.arg]</tt>.
+ * - #quo:: Returns the value of +self+ divided by the given value.
+ * - #real:: Returns the real part of +self+.
+ * - #rect (aliased as #rectangular):: Returns the array <tt>[self, 0]</tt>.
+ * - #remainder:: Returns <tt>self-arg*(self/arg).truncate</tt> for the given +arg+.
+ * - #round:: Returns the value of +self+ rounded to the nearest value
+ *            for the given a precision.
+ * - #to_c:: Returns the Complex representation of +self+.
+ * - #to_int:: Returns the Integer representation of +self+, truncating if necessary.
+ * - #truncate:: Returns +self+ truncated (toward zero) to a given precision.
+ *
+ * === Other
+ *
+ * - #clone:: Returns +self+; does not allow freezing.
+ * - #dup (aliased as #+@):: Returns +self+.
+ * - #step:: Invokes the given block with the sequence of specified numbers.
+ *
  */
 void
 Init_Numeric(void)
diff --git a/string.c b/string.c
index d763120095..94f6a81ce3 100644
--- a/string.c
+++ b/string.c
@@ -11564,8 +11564,10 @@ rb_enc_interned_str_cstr(const char *ptr, rb_encoding *enc)
  *
  *  == What's Here
  *
- *  First, what's elsewhere. \String includes the module Comparable,
- *  which provides several very useful methods.
+ *  First, what's elsewhere. \Class \String:
+ *
+ *  - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
+ *  - Includes {module Comparable}[Comparable.html#module-Comparable-label-What-27s+Here].
  *
  *  Here, class \String provides methods that are useful for:
  *