[DOC] Enhanced RDoc for NilClass (#7500)

1 files changed, 101 insertions, 45 deletions

diff --git a/object.c b/object.c
index b689d5c9b1..0256297b10 100644
--- a/object.c
+++ b/object.c
@@ -106,13 +106,17 @@ rb_obj_setup(VALUE obj, VALUE klass, VALUE type)
     return obj;
 }
 
-/**
- *  call-seq:
- *     obj === other   -> true or false
+/*
+ * call-seq:
+ *   nil === other -> true or false
  *
- *  Case Equality -- For class Object, effectively the same as calling
- *  <code>#==</code>, but typically overridden by descendants to provide
- *  meaningful semantics in +case+ statements.
+ * Returns +true+ or +false+.
+ *
+ * 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    -> ""
+ * call-seq:
+ *   to_s -> ''
+ *
+ * Returns an empty String:
+ *
+ *   nil.to_s # => ""
  *
- *  Always returns the empty string.
  */
 
 VALUE
@@ -1270,12 +1304,13 @@ rb_nil_to_s(VALUE obj)
 /*
  * Document-method: to_a
  *
- *  call-seq:
- *     nil.to_a    -> []
+ * call-seq:
+ *   to_a -> []
+ *
+ * Returns an empty Array.
  *
- *  Always returns an empty array.
+ *   nil.to_a # => []
  *
- *     nil.to_a   #=> []
  */
 
 static VALUE
@@ -1287,12 +1322,13 @@ nil_to_a(VALUE obj)
 /*
  * Document-method: to_h
  *
- *  call-seq:
- *     nil.to_h    -> {}
+ * call-seq:
+ *   to_h -> {}
+ *
+ * Returns an empty Hash.
  *
- *  Always returns an empty hash.
+ *   nil.to_h   #=> {}
  *
- *     nil.to_h   #=> {}
  */
 
 static VALUE
@@ -1302,10 +1338,13 @@ nil_to_h(VALUE obj)
 }
 
 /*
- *  call-seq:
- *    nil.inspect  -> "nil"
+ * call-seq:
+ *   inspect -> 'nil'
+ *
+ * Returns string <tt>'nil'</tt>:
+ *
+ *   nil.inspect # => "nil"
  *
- *  Always returns the string "nil".
  */
 
 static VALUE
@@ -1315,12 +1354,17 @@ nil_inspect(VALUE obj)
 }
 
 /*
- *  call-seq:
- *     nil =~ other  -> nil
+ * call-seq:
+ *   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
@@ -1430,15 +1474,20 @@ rb_false_to_s(VALUE obj)
 }
 
 /*
- *  call-seq:
- *     false & obj   -> false
- *     nil & obj     -> false
+ * call-seq:
+ *   false & object -> 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)
 {
@@ -1447,24 +1496,30 @@ false_and(VALUE obj, VALUE obj2)
 
 
 /*
- *  call-seq:
- *     false | obj   ->   true or false
- *     nil   | obj   ->   true or false
+ * call-seq:
+ *   false | object -> 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
- *     nil   ^ obj    -> true or false
+ * call-seq:
+ *   false ^ object -> true or false
+ *   nil ^ object   -> true or false
+ *
+ * Returns +false+ if +object+ is +nil+ or +false+, +true+ otherwise:
  *
- *  Exclusive Or---If <i>obj</i> is <code>nil</code> or
- *  <code>false</code>, returns <code>false</code>; otherwise, returns
- *  <code>true</code>.
+ *   nil ^ nil        # => false
+ *   nil ^ false      # => false
+ *   nil ^ Object.new # => true
  *
  */
 
@@ -1472,9 +1527,10 @@ false_and(VALUE obj, VALUE obj2)
 
 /*
  * call-seq:
- *   nil.nil?               -> true
+ *   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