Merge pull request microsoft#33372 from m1gu3l/patch-1

Better Array.sort compareFn docs

Author: Orta

src/lib/es5.d.ts

@@ -1235,7 +1235,12 @@ interface Array<T> {
     slice(start?: number, end?: number): T[];
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: T, b: T) => number): this;
     /**
@@ -1876,8 +1881,12 @@ interface Int8Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -2151,8 +2160,12 @@ interface Uint8Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -2426,8 +2439,12 @@ interface Uint8ClampedArray {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -2699,8 +2716,12 @@ interface Int16Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -2975,8 +2996,12 @@ interface Uint16Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -3250,8 +3275,12 @@ interface Int32Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -3524,8 +3553,12 @@ interface Uint32Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -3799,8 +3832,12 @@ interface Float32Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 
@@ -4075,8 +4112,12 @@ interface Float64Array {
 
     /**
      * Sorts an array.
-     * @param compareFn The name of the function used to determine the order of the elements. If
-     * omitted, the elements are sorted in ascending, ASCII character order.
+     * @param compareFn Function used to determine the order of the elements. It is expected to return
+     * a negative value if first argument is less than second argument, zero if they're equal and a positive
+     * value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
+     * ```ts
+     * [11,2,22,1].sort((a, b) => a - b)
+     * ```
      */
     sort(compareFn?: (a: number, b: number) => number): this;
 

tests/baselines/reference/destructuringParameterDeclaration4.errors.txt

@@ -41,7 +41,7 @@ tests/cases/conformance/es6/destructuring/destructuringParameterDeclaration4.ts(
     a1(...array2);            // Error parameter type is (number|string)[]
           ~~~~~~
 !!! error TS2552: Cannot find name 'array2'. Did you mean 'Array'?
-!!! related TS2728 /.ts/lib.es5.d.ts:1368:13: 'Array' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1373:13: 'Array' is declared here.
     a5([1, 2, "string", false, true]);       // Error, parameter type is [any, any, [[any]]]
               ~~~~~~~~
 !!! error TS2322: Type 'string' is not assignable to type '[[any]]'.

tests/baselines/reference/promisePermutations.errors.txt

@@ -447,7 +447,7 @@ tests/cases/compiler/promisePermutations.ts(160,21): error TS2769: No overload m
 !!! error TS2769:   The last overload gave the following error.
 !!! error TS2769:     Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
 !!! error TS2769:       Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1413:5: 'catch' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1418:5: 'catch' is declared here.
 !!! related TS2771 tests/cases/compiler/promisePermutations.ts:5:5: The last overload is declared here.
     var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
 

tests/baselines/reference/promisePermutations2.errors.txt

@@ -351,7 +351,7 @@ tests/cases/compiler/promisePermutations2.ts(159,21): error TS2345: Argument of
                                        ~~~~~~~~~
 !!! error TS2345: Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
 !!! error TS2345:   Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1413:5: 'catch' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1418:5: 'catch' is declared here.
     var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
 
     var r11: IPromise<number>;

tests/baselines/reference/promisePermutations3.errors.txt

@@ -398,7 +398,7 @@ tests/cases/compiler/promisePermutations3.ts(165,21): error TS2345: Argument of
 !!! error TS2769:   The last overload gave the following error.
 !!! error TS2769:     Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
 !!! error TS2769:       Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1413:5: 'catch' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1418:5: 'catch' is declared here.
 !!! related TS2771 tests/cases/compiler/promisePermutations3.ts:7:5: The last overload is declared here.
     var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
 
@@ -445,5 +445,5 @@ tests/cases/compiler/promisePermutations3.ts(165,21): error TS2345: Argument of
                         ~~~~~~~~~~~~~~~
 !!! error TS2345: Argument of type '{ <T>(x: T): IPromise<T>; <T>(x: T, y: T): Promise<T>; }' is not assignable to parameter of type '(value: (x: any) => any) => Promise<unknown>'.
 !!! error TS2345:   Property 'catch' is missing in type 'IPromise<any>' but required in type 'Promise<unknown>'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1413:5: 'catch' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1418:5: 'catch' is declared here.
     var s12c = s12.then(testFunction12P, testFunction12, testFunction12); // ok

tests/baselines/reference/promiseTypeInference.errors.txt

@@ -32,7 +32,7 @@ tests/cases/compiler/promiseTypeInference.ts(10,39): error TS2769: No overload m
 !!! error TS2769:           Types of parameters 'success' and 'onfulfilled' are incompatible.
 !!! error TS2769:             Type 'TResult1 | PromiseLike<TResult1>' is not assignable to type 'IPromise<TResult1 | TResult2>'.
 !!! error TS2769:               Type 'TResult1' is not assignable to type 'IPromise<TResult1 | TResult2>'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1413:5: 'catch' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1418:5: 'catch' is declared here.
 !!! related TS6502 tests/cases/compiler/promiseTypeInference.ts:2:23: The expected type comes from the return type of this signature.
-!!! related TS6502 /.ts/lib.es5.d.ts:1406:57: The expected type comes from the return type of this signature.
+!!! related TS6502 /.ts/lib.es5.d.ts:1411:57: The expected type comes from the return type of this signature.
 

tests/baselines/reference/redefineArray.errors.txt

@@ -5,4 +5,4 @@ tests/cases/compiler/redefineArray.ts(1,1): error TS2741: Property 'isArray' is
     Array = function (n:number, s:string) {return n;};
     ~~~~~
 !!! error TS2741: Property 'isArray' is missing in type '(n: number, s: string) => number' but required in type 'ArrayConstructor'.
-!!! related TS2728 /.ts/lib.es5.d.ts:1364:5: 'isArray' is declared here.
+!!! related TS2728 /.ts/lib.es5.d.ts:1369:5: 'isArray' is declared here.