Allow different values than only -1, 0 and 1 to be returned by <=>

spec/std/array_spec.cr

@@ -1180,7 +1180,7 @@ describe "Array" do
     b = [4, 5, 6]
     c = [1, 2]
 
-    (a <=> b).should be < 1
+    (a <=> b).should be < 0
     (a <=> c).should be > 0
     (b <=> c).should be > 0
     (b <=> a).should be > 0

src/array.cr

@@ -167,11 +167,11 @@ class Array(T)
     false
   end
 
-  # Combined comparison operator. Returns *0* if `self` equals *other*, *1* if
-  # `self` is greater than *other* and *-1* if `self` is smaller than *other*.
+  # Combined comparison operator. Returns `0` if `self` equals *other*, `1` if
+  # `self` is greater than *other* and `-1` if `self` is smaller than *other*.
   #
   # It compares the elements of both arrays in the same position using the
-  # `<=>` operator.  As soon as one of such comparisons returns a non-zero
+  # `<=>` operator. As soon as one of such comparisons returns a non-zero
   # value, that result is the return value of the comparison.
   #
   # If all elements are equal, the comparison is based on the size of the arrays.

src/char.cr

@@ -103,10 +103,17 @@ struct Char
     (ord - other).chr
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
+  #
+  # Returns a negative difference of the codepoint values of this char and *other*
+  # if `self`'s codepoint is less than *other*'s codepoint, zero if `self`'s codepoint equals *other*'s
+  # codepoint, or a positive difference of the codepoint values of this char and *other*
+  # if `self`'s codepoint greater than *other*'s codepoint.
   #
   # ```
   # 'a' <=> 'c' # => -2
+  # 'z' <=> 'z' # => 0
+  # 'c' <=> 'a' # => 2
   # ```
   def <=>(other : Char)
     self - other

src/comparable.cr

@@ -1,22 +1,22 @@
 # The `Comparable` mixin is used by classes whose objects may be ordered.
 #
 # Including types must provide an `<=>` method, 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.
+# another object, returning a negative number, zero, or a positive number depending
+# on whether the receiver is less than, equal to, or greater than the other object.
 #
 # `Comparable` uses `<=>` to implement the conventional comparison operators (`<`, `<=`, `==`, `>=`, and `>`).
 module Comparable(T)
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `-1`.
+  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns a negative number.
   def <(other : T)
     (self <=> other) < 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `-1` or `0`.
+  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns a negative number or zero.
   def <=(other : T)
     (self <=> other) <= 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `0`.
+  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns zero.
   # Also returns `true` if this and *other* are the same object.
   def ==(other : T)
     if self.is_a?(Reference)
@@ -30,18 +30,20 @@ module Comparable(T)
     (self <=> other) == 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `1`.
+  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns a positive number.
   def >(other : T)
     (self <=> other) > 0
   end
 
-  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns `1` or `0`.
+  # Compares this object to *other* based on the receiver’s `<=>` method, returning `true` if it returns a positive number or zero.
   def >=(other : T)
     (self <=> other) >= 0
   end
 
-  # Comparison operator. Returns `0` if the two objects are equal,
-  # a negative number if this object is considered less than *other*,
+  # The comparison operator.
+  #
+  # Returns zero if the two objects are equal,
+  # a negative number if this object is considered to be less than *other*,
   # or a positive number otherwise.
   #
   # Subclasses define this method to provide class-specific ordering.

src/number.cr

@@ -161,9 +161,10 @@ struct Number
     {(self / number).floor, self % number}
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
   #
-  # See also: `Object#<=>`.
+  # Returns `-1` if `self` is less than *other*, `0` if `self` equals *other*
+  # or `1` if `self` is greater than *other*.
   def <=>(other)
     self > other ? 1 : (self < other ? -1 : 0)
   end

src/partial_comparable.cr

@@ -1,31 +1,31 @@
 # The `PartialComparable` mixin is used by classes whose objects may be partially ordered.
 #
 # Including types must provide an `<=>` method, which compares the receiver against
-# another object, returning `-1`, `0`, `+1` or `nil` depending on whether
+# another object, returning a negative number, zero, a positive number or `nil` depending on whether
 # the receiver is less than, equal to, greater than the other object,
 # or no order can be established.
 #
 # `PartialComparable` uses `<=>` to implement the conventional
 # comparison operators (`<`, `<=`, `==`, `>=`, and `>`).
 module PartialComparable(T)
   # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `-1`.
+  # returning `true` if it returns a negative number.
   def <(other : T)
     compare_with(other) do |cmp|
       cmp < 0
     end
   end
 
   # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `-1` or `0`.
+  # returning `true` if it returns a negative number or zero.
   def <=(other : T)
     compare_with(other) do |cmp|
       cmp <= 0
     end
   end
 
   # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `0`.
+  # returning `true` if it returns zero.
   # Also returns `true` if this and *other* are the same object.
   def ==(other : T)
     if self.is_a?(Reference) && (other.is_a?(Reference) || other.is_a?(Nil))
@@ -38,15 +38,15 @@ module PartialComparable(T)
   end
 
   # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `1`.
+  # returning `true` if it returns a positive number.
   def >(other : T)
     compare_with(other) do |cmp|
       cmp > 0
     end
   end
 
   # Compares this object to *other* based on the receiver’s `<=>` method,
-  # returning `true` if it returns `1` or `0`.
+  # returning `true` if it returns a positive number or zero.
   def >=(other : T)
     compare_with(other) do |cmp|
       cmp >= 0
@@ -62,5 +62,18 @@ module PartialComparable(T)
     end
   end
 
+  # The comparison operator.
+  #
+  # Returns a negative number if the object
+  # is considered to be less than *other*, zero if the two objects are equal,
+  # a positive number if this object is considered to be greater than *other*,
+  # or `nil` if no order can be established.
+  #
+  # Subclasses define this method to provide class-specific ordering.
+  #
+  # ```
+  # # Sort in a descending way
+  # [4, 7, 2].sort { |x, y| y <=> x } # => [7, 4, 2]
+  # ```
   abstract def <=>(other : T)
 end

src/pointer.cr

@@ -98,10 +98,8 @@ struct Pointer(T)
     self + (-other.to_i64!)
   end
 
-  # Returns -1, 0 or 1 if this pointer's address is less, equal or greater than *other*'s address,
+  # Returns `-1`, `0` or `1` if this pointer's address is less, equal or greater than *other*'s address,
   # respectively.
-  #
-  # See also: `Object#<=>`.
   def <=>(other : self)
     address <=> other.address
   end

src/semantic_version.cr

@@ -78,7 +78,10 @@ struct SemanticVersion
     end
   end
 
-  # The comparison operator
+  # The comparison operator.
+  #
+  # Returns `-1` if `self`'s version is lower than *other*'s, `0` if `self`'s version equals *other*'s
+  # or `-1` if `self`'s version is greater than *other*'s.
   #
   # ```
   # require "semantic_version"
@@ -145,7 +148,10 @@ struct SemanticVersion
       identifiers.join('.', io)
     end
 
-    # The comparison operator
+    # The comparison operator.
+    #
+    # Returns `-1` if `self`'s pre-release is lower than *other*'s, `0` if `self`'s pre-release equals *other*'s
+    # or `-1` if `self`'s pre-release is greater than *other*'s.
     #
     # ```
     # require "semantic_version"

src/string.cr

@@ -2361,7 +2361,9 @@ class String
     to_unsafe.memcmp(other.to_unsafe, bytesize) == 0
   end
 
-  # Compares this string with *other*, returning `-1`, `0` or `+1` depending on whether
+  # The comparison operator.
+  #
+  # Compares this string with *other*, returning `-1`, `0` or `1` depending on whether
   # this string is less, equal or greater than *other*.
   #
   # Comparison is done byte-per-byte: if a byte is less then the other corresponding
@@ -2385,7 +2387,7 @@ class String
     cmp == 0 ? (bytesize <=> other.bytesize) : cmp.sign
   end
 
-  # Compares this string with *other*, returning `-1`, `0` or `+1` depending on whether
+  # Compares this string with *other*, returning `-1`, `0` or `1` depending on whether
   # this string is less, equal or greater than *other*, optionally in a *case_insensitive*
   # manner.
   #

src/symbol.cr

@@ -21,7 +21,7 @@ struct Symbol
   end
 
   # Compares symbol with other based on `String#<=>` method. Returns `-1`, `0`
-  # or `+1` depending on whether symbol is less than, equal to,
+  # or `1` depending on whether symbol is less than, equal to,
   # or greater than *other*.
   #
   # See `String#<=>` for more information.

src/tuple.cr

@@ -269,13 +269,13 @@ struct Tuple
     true
   end
 
-  # Implements the comparison operator.
+  # The comparison operator.
   #
-  # Each object in each tuple is compared (using the `<=>` operator).
+  # Each object in each tuple is compared using the `<=>` operator.
   #
   # Tuples are compared in an "element-wise" manner; the first element of this tuple is
   # compared with the first one of *other* using the `<=>` operator, then each of the second elements,
-  # etc. As soon as the result of any such comparison is non zero
+  # etc. As soon as the result of any such comparison is non-zero
   # (i.e. the two corresponding elements are not equal), that result is returned for the whole tuple comparison.
   #
   # If all the elements are equal, then the result is based on a comparison of the tuple sizes.
@@ -284,11 +284,9 @@ struct Tuple
   #
   # ```
   # {"a", "a", "c"} <=> {"a", "b", "c"} # => -1
-  # {1, 2, 3, 4, 5, 6} <=> {1, 2}       # => +1
+  # {1, 2, 3, 4, 5, 6} <=> {1, 2}       # => 1
   # {1, 2} <=> {1, 2.0}                 # => 0
   # ```
-  #
-  # See also: `Object#<=>`.
   def <=>(other : self)
     {% for i in 0...T.size %}
       cmp = self[{{i}}] <=> other[{{i}}]