Fixup for #1435.

0.17.0-release-notes.md

@@ -67,9 +67,9 @@ New features in the standard library:
 -   The `store:` module now exposes all functionalities of Elvish's persistent
     store.
 
--   New `compare` command to allow efficient comparison of numbers, strings, and
-    lists ([#1347](https://b.elv.sh/1347)). This is the default comparator used
-    by `order`.
+-   New `compare` command to compare numbers, strings, and lists
+    ([#1347](https://b.elv.sh/1347)), in a consistent way as the `order`
+    builtin.
 
 Performance improvements:
 

pkg/eval/builtin_fn_container.go

@@ -904,20 +904,8 @@ func keys(fm *Frame, v interface{}) error {
 // argument. If the function throws an exception, `order` rethrows the exception
 // without outputting any value.
 //
-// If `&less-than` has value `$nil` (the default if not set), the following
-// comparison algorithm is used:
-//
-// - Numbers are compared numerically. For the sake of sorting, `NaN` is treated
-//   as smaller than all other numbers.
-//
-// - Strings are compared lexicographically by bytes, which is equivalent to
-//   comparing by codepoints under UTF-8.
-//
-// - Lists are compared lexicographically by elements, if the elements at the
-//   same positions are comparable.
-//
-// If the ordering between two elements are not defined by the conditions above,
-// no value is outputted and an exception is thrown.
+// If `&less-than` has value `$nil` (the default if not set), it is equivalent
+// to `{|a b| eq -1 (compare $a $b) }`.
 //
 // Examples:
 //
@@ -1066,35 +1054,40 @@ const (
 // compare $a $b
 // ```
 //
-// Outputs -1 if `$a` is less than `$b`, 0 if equal, and 1 if greater than.
+// Outputs -1 if `$a` < `$b`, 0 if `$a` = `$b`, and 1 if `$a` > `$b`.
 //
 // The following comparison algorithm is used:
 //
-// - Numbers are compared numerically. `NaN` is treated as smaller than all other numbers.
+// - Typed numbers are compared numerically. The comparison is consistent with
+//   the [number comparison commands](#num-cmp), except that `NaN` values are
+//   considered equal to each other and smaller than all other numbers.
 //
-// - Strings are compared lexicographically by bytes, which is equivalent to
-//   comparing by codepoints under UTF-8.
+// - Strings are compared lexicographically by bytes, consistent with the
+//   [string comparison commands](#str-cmp). For UTF-8 encoded strings, this is
+//   equivalent to comparing by codepoints.
 //
 // - Lists are compared lexicographically by elements, if the elements at the
 //   same positions are comparable.
 //
-// If the ordering between two elements is not defined by the conditions above a "bad value"
-// exception is thrown.
+// If the ordering between two elements is not defined by the conditions above,
+// i.e. if the value of `$a` or `$b` is not covered by any of the cases above or
+// if they belong to different cases, a "bad value" exception is thrown.
 //
 // Examples:
 //
 // ```elvish-transcript
 // ~> compare a b
-// ▶ 1
+// ▶ (num 1)
 // ~> compare b a
-// ▶ -1
+// ▶ (num -1)
 // ~> compare x x
-// ▶ 0
-// ~> order (float64 10) (float64 1)
-// ▶ 1
+// ▶ (num 0)
+// ~> compare (float64 10) (float64 1)
+// ▶ (num 1)
 // ```
 //
-// Beware that strings that look like numbers are treated as strings, not numbers.
+// Beware that strings that look like numbers are treated as strings, not
+// numbers.
 //
 // @cf order
 

pkg/eval/builtin_fn_container_test.go

@@ -268,16 +268,16 @@ func TestOrder(t *testing.T) {
 		That("put foo bar bar | order").Puts("bar", "bar", "foo"),
 		That("put 10 1 5 2 | order").Puts("1", "10", "2", "5"),
 
-		// Ordering numbers
-		// Only small integers normalized to the "num" type.
+		// Ordering typed numbers
+		// Only small integers
 		That("put 10 1 1 | each $num~ | order").Puts(1, 1, 10),
 		That("put 10 1 5 2 -1 | each $num~ | order").Puts(-1, 1, 2, 5, 10),
-		// Small and large integers normalized to the "num" type.
+		// Small and large integers
 		That("put 1 "+z+" 2 "+z+" | each $num~ | order").Puts(1, 2, bigInt(z), bigInt(z)),
 		// Integers and rationals
 		That("put 1 2 3/2 3/2 | each $num~ | order").
 			Puts(1, big.NewRat(3, 2), big.NewRat(3, 2), 2),
-		// Integers and floats normalized to the "num" type.
+		// Integers and floats
 		That("put 1 1.5 2 1.5 | each $num~ | order").
 			Puts(1, 1.5, 1.5, 2),
 		// Mixed integers and floats.