Small doc and code improvements

src/comparable.cr

@@ -8,14 +8,15 @@
 # - `nil` if `self` and the other object are not comparable
 #
 # `Comparable` uses `<=>` to implement the conventional comparison operators
-# (`<`, `<=`, `==`, `>=`, and `>`).
+# (`<`, `<=`, `==`, `>=`, and `>`). All of these return `false` when `<=>`
+# returns `nil`.
 #
 # Note that returning `nil` is only useful when defining a partial comparable
 # relationship. One such example is float values: they are generally comparable,
 # except for `NaN`. If none of the values of a type are comparable between each
 # other, `Comparable` shouldn't be included.
 #
-# NOTE: when `nil` is returned from `<=>`, `Array#sort` and related sorting
+# NOTE: When `nil` is returned from `<=>`, `Array#sort` and related sorting
 # methods will perform slightly slower.
 module Comparable(T)
   # Compares this object to *other* based on the receiver’s `<=>` method,

src/compiler/crystal/macros/methods.cr

@@ -423,9 +423,7 @@ module Crystal
         bool_bin_op(method, args) { |me, other| me <= other }
       when "<=>"
         num_bin_op(method, args) do |me, other|
-          v = me <=> other
-          return NilLiteral.new if v.nil?
-          v
+          (me <=> other) || (return NilLiteral.new)
         end
       when "+"
         if args.empty?

src/int.cr

@@ -237,7 +237,7 @@ struct Int
     end
   end
 
-  def <=>(other : Int)
+  def <=>(other : Int) : Int32
     # Override Number#<=> because when comparing
     # Int vs Int there's no way we can return `nil`
     self > other ? 1 : (self < other ? -1 : 0)

src/number.cr

@@ -163,9 +163,12 @@ struct Number
 
   # The comparison operator.
   #
-  # Returns `-1`, `0` or `1` depending on whether `self` is less than *other*, equals *other*
-  # or is greater than *other*.
-  def <=>(other)
+  # Returns:
+  # - `-1` if `self` is less than *other*
+  # - `0` if `self` is equal to *other*
+  # - `-1` if `self` is greater than *other*
+  # - `nil` if self is `NaN` or *other* is `NaN`, because `NaN` values are not comparable
+  def <=>(other) : Int32?
     # NaN can't be compared to other numbers
     return nil if self.is_a?(Float) && self.nan?
     return nil if other.is_a?(Float) && other.nan?