[DOC] Harmonize lt methods

Merged: https://github.com/ruby/ruby/pull/15593

Merged-By: peterzhu2118 <peter@peterzhu.ca>

compar.c

@@ -123,10 +123,14 @@ cmp_ge(VALUE x, VALUE y)
 
 /*
  *  call-seq:
- *     obj < other    -> true or false
+ *    self < other -> true or false
+ *
+ *  Returns whether +self+ is "less than" +other+;
+ *  equivalent to <tt>(self <=> other) < 0</tt>:
+ *
+ *    'foo' < 'foo'  # => false
+ *    'foo' < 'food' # => true
  *
- *  Compares two objects based on the receiver's <code><=></code>
- *  method, returning true if it returns a value less than 0.
  */
 
 static VALUE

hash.c

@@ -4915,10 +4915,9 @@ rb_hash_le(VALUE hash, VALUE other)
 
 /*
  *  call-seq:
- *    self < other_hash -> true or false
+ *    self < other -> true or false
  *
- *  Returns +true+ if the entries of +self+ are a proper subset of the entries of +other_hash+,
- *  +false+ otherwise:
+ *  Returns whether the entries of +self+ are a proper subset of the entries of +other+:
  *
  *    h = {foo: 0, bar: 1}
  *    h < {foo: 0, bar: 1, baz: 2} # => true   # Proper subset.

numeric.c

@@ -1702,7 +1702,8 @@ flo_ge(VALUE x, VALUE y)
  *  call-seq:
  *    self < other -> true or false
  *
- *  Returns +true+ if +self+ is numerically less than +other+:
+ *  Returns whether the value of +self+ is less than the value of +other+;
+ *  +other+ must be numeric, but may not be Complex:
  *
  *    2.0 < 3              # => true
  *    2.0 < 3.0            # => true
@@ -1710,7 +1711,6 @@ flo_ge(VALUE x, VALUE y)
  *    2.0 < 2.0            # => false
  *
  *  <tt>Float::NAN < Float::NAN</tt> returns an implementation-dependent value.
- *
  */
 
 static VALUE
@@ -5038,7 +5038,8 @@ fix_lt(VALUE x, VALUE y)
  * call-seq:
  *    self < other -> true or false
  *
- * Returns +true+ if the value of +self+ is less than that of +other+:
+ * Returns whether the value of +self+ is less than the value of +other+;
+ * +other+ must be numeric, but may not be Complex:
  *
  *    1 < 0              # => false
  *    1 < 1              # => false
@@ -5046,8 +5047,6 @@ fix_lt(VALUE x, VALUE y)
  *    1 < 0.5            # => false
  *    1 < Rational(1, 2) # => false
  *
- *  Raises an exception if the comparison cannot be made.
- *
  */
 
 static VALUE

object.c

@@ -1948,14 +1948,15 @@ rb_class_inherited_p(VALUE mod, VALUE arg)
 
 /*
  * call-seq:
- *   mod < other   ->  true, false, or nil
+ *   self < other -> true, false, or nil
  *
- * Returns true if <i>mod</i> is a subclass of <i>other</i>. Returns
- * <code>false</code> if <i>mod</i> is the same as <i>other</i>
- * or <i>mod</i> is an ancestor of <i>other</i>.
- * Returns <code>nil</code> if there's no relationship between the two.
- * (Think of the relationship in terms of the class definition:
- * "class A < B" implies "A < B".)
+ * Returns whether +self+ is a subclass of +other+,
+ * or +nil+ if there is no relationship between the two:
+ *
+ *   Float < Numeric # => true
+ *   Numeric < Float # => false
+ *   Float < Float   # => false
+ *   Float < Hash    # => nil
  *
  */