[DOC] Enhanced RDoc for NilClass (#7500)

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

complex.c

@@ -1692,9 +1692,12 @@ nucomp_to_c(VALUE self)
 
 /*
  * call-seq:
- *    nil.to_c  ->  (0+0i)
+ *   to_c -> (0+0i)
+ *
+ * Returns zero as a Complex:
+ *
+ *   nil.to_c # => (0+0i)
  *
- * Returns zero as a complex.
  */
 static VALUE
 nilclass_to_c(VALUE self)

object.c

@@ -106,13 +106,17 @@ rb_obj_setup(VALUE obj, VALUE klass, VALUE type)
     return obj;
 }
 
-/**
+/*
  * call-seq:
- *     obj === other   -> true or false
+ *   nil === other -> true or false
  *
- *  Case Equality -- For class Object, effectively the same as calling
+ * Returns +true+ or +false+.
- *  <code>#==</code>, but typically overridden by descendants to provide
+ *
- *  meaningful semantics in +case+ statements.
+ * Like Object#==, if +object+ is an instance of Object
+ * (and not an instance of one of its many subclasses).
+ *
+ * This method is commonly overridden by those subclasses,
+ * to provide meaningful semantics in +case+ statements.
  */
 #define case_equal rb_equal
     /* The default implementation of #=== is
@@ -1251,14 +1255,44 @@ rb_obj_frozen_p(VALUE obj)
 /*
  * Document-class: NilClass
  *
- *  The class of the singleton object <code>nil</code>.
+ * The class of the singleton object +nil+.
+ *
+ * Several of its methods act as operators:
+ *
+ * - #&
+ * - #|
+ * - #===
+ * - #=~
+ * - #^
+ *
+ * Others act as converters, carrying the concept of _nullity_
+ * to other classes:
+ *
+ * - #rationalize
+ * - #to_a
+ * - #to_c
+ * - #to_h
+ * - #to_r
+ * - #to_s
+ *
+ * Another method provides inspection:
+ *
+ * - #inspect
+ *
+ * Finally, there is this query method:
+ *
+ * - #nil?
+ *
  */
 
 /*
  * call-seq:
- *     nil.to_s    -> ""
+ *   to_s -> ''
+ *
+ * Returns an empty String:
+ *
+ *   nil.to_s # => ""
  *
- *  Always returns the empty string.
  */
 
 VALUE
@@ -1271,11 +1305,12 @@ rb_nil_to_s(VALUE obj)
  * Document-method: to_a
  *
  * call-seq:
- *     nil.to_a    -> []
+ *   to_a -> []
  *
- *  Always returns an empty array.
+ * Returns an empty Array.
+ *
+ *   nil.to_a # => []
  *
- *     nil.to_a   #=> []
  */
 
 static VALUE
@@ -1288,11 +1323,12 @@ nil_to_a(VALUE obj)
  * Document-method: to_h
  *
  * call-seq:
- *     nil.to_h    -> {}
+ *   to_h -> {}
  *
- *  Always returns an empty hash.
+ * Returns an empty Hash.
  *
  *   nil.to_h   #=> {}
+ *
  */
 
 static VALUE
@@ -1303,9 +1339,12 @@ nil_to_h(VALUE obj)
 
 /*
  * call-seq:
- *    nil.inspect  -> "nil"
+ *   inspect -> 'nil'
+ *
+ * Returns string <tt>'nil'</tt>:
+ *
+ *   nil.inspect # => "nil"
  *
- *  Always returns the string "nil".
  */
 
 static VALUE
@@ -1316,11 +1355,16 @@ nil_inspect(VALUE obj)
 
 /*
  * call-seq:
- *     nil =~ other  -> nil
+ *   nil =~ object -> nil
  *
- *  Dummy pattern matching -- always returns nil.
+ * Returns +nil+.
+ *
+ * This method makes it useful to write:
+ *
+ *   while gets =~ /re/
+ *     # ...
+ *   end
  *
- *  This method makes it possible to `while gets =~ /re/ do`.
  */
 
 static VALUE
@@ -1431,14 +1475,19 @@ rb_false_to_s(VALUE obj)
 
 /*
  * call-seq:
- *     false & obj   -> false
+ *   false & object -> false
- *     nil & obj     -> false
+ *   nil & object   -> false
+ *
+ * Returns +false+:
+ *
+ *   false & true       # => false
+ *   false & Object.new # => false
+ *
+ * Argument +object+ is evaluated:
+ *
+ *   false & raise # Raises RuntimeError.
  *
- *  And---Returns <code>false</code>. <i>obj</i> is always
- *  evaluated as it is the argument to a method call---there is no
- *  short-circuit evaluation in this case.
  */
-
 static VALUE
 false_and(VALUE obj, VALUE obj2)
 {
@@ -1448,23 +1497,29 @@ false_and(VALUE obj, VALUE obj2)
 
 /*
  * call-seq:
- *     false | obj   ->   true or false
+ *   false | object -> true or false
- *     nil   | obj   ->   true or false
+ *   nil   | object -> true or false
+ *
+ * Returns +false+ if +object+ is +nil+ or +false+, +true+ otherwise:
+ *
+ *   nil | nil        # => false
+ *   nil | false      # => false
+ *   nil | Object.new # => true
  *
- *  Or---Returns <code>false</code> if <i>obj</i> is
- *  <code>nil</code> or <code>false</code>; <code>true</code> otherwise.
  */
 
 #define false_or true_and
 
 /*
  * call-seq:
- *     false ^ obj    -> true or false
+ *   false ^ object -> true or false
- *     nil   ^ obj    -> true or false
+ *   nil ^ object   -> true or false
  *
- *  Exclusive Or---If <i>obj</i> is <code>nil</code> or
+ * Returns +false+ if +object+ is +nil+ or +false+, +true+ otherwise:
- *  <code>false</code>, returns <code>false</code>; otherwise, returns
+ *
- *  <code>true</code>.
+ *   nil ^ nil        # => false
+ *   nil ^ false      # => false
+ *   nil ^ Object.new # => true
  *
  */
 
@@ -1474,7 +1529,8 @@ false_and(VALUE obj, VALUE obj2)
  * call-seq:
  *   nil.nil?  -> true
  *
- * Only the object <i>nil</i> responds <code>true</code> to <code>nil?</code>.
+ * Returns +true+.
+ * For all other objects, method <tt>nil?</tt> returns +false+.
  */
 
 static VALUE

rational.c

@@ -2103,9 +2103,12 @@ rb_float_denominator(VALUE self)
 
 /*
  * call-seq:
- *    nil.to_r  ->  (0/1)
+ *   to_r  ->  (0/1)
+ *
+ * Returns zero as a Rational:
+ *
+ *   nil.to_r # => (0/1)
  *
- * Returns zero as a rational.
  */
 static VALUE
 nilclass_to_r(VALUE self)
@@ -2115,10 +2118,14 @@ nilclass_to_r(VALUE self)
 
 /*
  * call-seq:
- *    nil.rationalize([eps])  ->  (0/1)
+ *   rationalize(eps = nil)  ->  (0/1)
+ *
+ * Returns zero as a Rational:
+ *
+ *   nil.rationalize # => (0/1)
+ *
+ * Argument +eps+ is ignored.
  *
- * Returns zero as a rational.  The optional argument +eps+ is always
- * ignored.
  */
 static VALUE
 nilclass_rationalize(int argc, VALUE *argv, VALUE self)