6 files changed, 11 insertions, 9 deletions
diff --git a/array.c b/array.c
index f1927d265a..1deda03482 100644
--- a/array.c
+++ b/array.c
@@ -2963,7 +2963,7 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur)
 
 /*
  *  call-seq:
- *     array <=> other_array   ->  -1, 0, +1, nil
+ *     array <=> other_array   ->  -1, 0, +1 or nil
  *
  *  Comparison---Returns an integer (-1, 0,
  *  or +1) if this array is less than, equal to, or greater than
diff --git a/bignum.c b/bignum.c
index df66d33667..d1c9820ee7 100644
--- a/bignum.c
+++ b/bignum.c
@@ -1273,7 +1273,7 @@ rb_big_to_f(VALUE x)
 
 /*
  *  call-seq:
- *     big <=> numeric   => -1, 0, +1
+ *     big <=> numeric   => -1, 0, +1 or nil
  *
  *  Comparison---Returns -1, 0, or +1 depending on whether <i>big</i> is
  *  less than, equal to, or greater than <i>numeric</i>. This is the
diff --git a/compar.c b/compar.c
index e8ebfc5bfa..4db42913db 100644
--- a/compar.c
+++ b/compar.c
@@ -163,7 +163,9 @@ cmp_between(VALUE x, VALUE min, VALUE max)
  *  may be ordered. The class must define the <code><=></code> operator,
  *  which compares the receiver against another object, returning -1, 0,
  *  or +1 depending on whether the receiver is less than, equal to, or
- *  greater than the other object. <code>Comparable</code> uses
+ *  greater than the other object. If the other object is not comparable
+ *  then the <code><=></code> operator should return nil.
+ *  <code>Comparable</code> uses
  *  <code><=></code> to implement the conventional comparison operators
  *  (<code><</code>, <code><=</code>, <code>==</code>, <code>>=</code>,
  *  and <code>></code>) and the method <code>between?</code>.
diff --git a/file.c b/file.c
index 11d25f85a6..880523cefe 100644
--- a/file.c
+++ b/file.c
@@ -223,7 +223,7 @@ static struct timespec stat_mtimespec(struct stat *st);
 
 /*
  *  call-seq:
- *     stat <=> other_stat    => -1, 0, 1
+ *     stat <=> other_stat    => -1, 0, 1, nil
  *
  *  Compares <code>File::Stat</code> objects by comparing their
  *  respective modification times.
diff --git a/string.c b/string.c
index 9999c8570a..4f607a4f2c 100644
--- a/string.c
+++ b/string.c
@@ -2162,7 +2162,7 @@ rb_str_eql(VALUE str1, VALUE str2)
 
 /*
  *  call-seq:
- *     str <=> other_str   => -1, 0, +1
+ *     str <=> other_str   => -1, 0, +1 or nil
  *
  *  Comparison---Returns -1 if <i>other_str</i> is greater than, 0 if
  *  <i>other_str</i> is equal to, and +1 if <i>other_str</i> is less than
@@ -2213,7 +2213,7 @@ rb_str_cmp_m(VALUE str1, VALUE str2)
 
 /*
  *  call-seq:
- *     str.casecmp(other_str)   => -1, 0, +1
+ *     str.casecmp(other_str)   => -1, 0, +1 or nil
  *
  *  Case-insensitive version of <code>String#<=></code>.
  *
@@ -7161,7 +7161,7 @@ sym_succ(VALUE sym)
 /*
  * call-seq:
  *
- *   str <=> other       => -1, 0, +1
+ *   str <=> other       => -1, 0, +1 or nil
  *
  * Compares _sym_ with _other_ in string form.
  */
@@ -7178,7 +7178,7 @@ sym_cmp(VALUE sym, VALUE other)
 /*
  * call-seq:
  *
- *   sym.casecmp(other)  => -1, 0, +1
+ *   sym.casecmp(other)  => -1, 0, +1 or nil
  *
  * Case-insensitive version of <code>Symbol#<=></code>.
  */
diff --git a/time.c b/time.c
index 775640acb7..d9b68a5da4 100644
--- a/time.c
+++ b/time.c
@@ -2489,7 +2489,7 @@ time_subsec(VALUE time)
 
 /*
  *  call-seq:
- *     time <=> other_time => -1, 0, +1
+ *     time <=> other_time => -1, 0, +1 or nil
  *
  *  Comparison---Compares <i>time</i> with <i>other_time</i>.
  *