From d29f56f940ac63133a081fec4f3fca3a035831fc Mon Sep 17 00:00:00 2001 From: Brandon Pickering Date: Mon, 14 Dec 2020 18:09:58 -0800 Subject: [PATCH 1/2] Improve documentation for basic array methods --- src/lib/es5.d.ts | 46 +++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/src/lib/es5.d.ts b/src/lib/es5.d.ts index 422f8cdfb2bc6..0fe2b0404c365 100644 --- a/src/lib/es5.d.ts +++ b/src/lib/es5.d.ts @@ -1199,7 +1199,7 @@ interface ConcatArray { interface Array { /** - * Gets or sets the length of the array. This is a number one higher than the highest element defined in an array. + * Gets or sets the length of the array. This is a number one higher than the highest index in the array. */ length: number; /** @@ -1212,44 +1212,54 @@ interface Array { toLocaleString(): string; /** * Removes the last element from an array and returns it. + * If the array is empty, undefined is returned and the array is not modified. */ pop(): T | undefined; /** - * Appends new elements to an array, and returns the new length of the array. - * @param items New elements of the Array. + * Appends new elements to the end of an array, and returns the new length of the array. + * @param items New elements to add to the array. */ push(...items: T[]): number; /** * Combines two or more arrays. - * @param items Additional items to add to the end of array1. + * This method returns a new array without modifying any existing arrays. + * @param items Additional arrays and/or items to add to the end of the array. */ concat(...items: ConcatArray[]): T[]; /** * Combines two or more arrays. - * @param items Additional items to add to the end of array1. + * This method returns a new array without modifying any existing arrays. + * @param items Additional arrays and/or items to add to the end of the array. */ concat(...items: (T | ConcatArray)[]): T[]; /** - * Adds all the elements of an array separated by the specified separator string. - * @param separator A string used to separate one element of an array from the next in the resulting String. If omitted, the array elements are separated with a comma. + * Adds all the elements of an array into a string, separated by the specified separator string. + * @param separator A string used to separate one element of the array from the next in the resulting string. If omitted, the array elements are separated with a comma. */ join(separator?: string): string; /** - * Reverses the elements in an Array. + * Reverses the elements in an array in place. + * This method mutates the array and returns a reference to the same array. */ reverse(): T[]; /** * Removes the first element from an array and returns it. + * If the array is empty, undefined is returned and the array is not modified. */ shift(): T | undefined; /** - * Returns a section of an array. - * @param start The beginning of the specified portion of the array. - * @param end The end of the specified portion of the array. This is exclusive of the element at the index 'end'. + * Returns a copy of a section of an array. + * For both start and end, a negative index can be used to indicate an offset from the end of the array. + * For example, -2 refers to the second to last element of the array. + * @param start The beginning index of the specified portion of the array. + * If start is undefined, then the slice begins at index 0. + * @param end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'. + * If end is undefined, then the slice extends to the end of the array. */ slice(start?: number, end?: number): T[]; /** - * Sorts an array. + * Sorts an array in place. + * This method mutates the array and returns a reference to the same array. * @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. @@ -1262,6 +1272,7 @@ interface Array { * Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements. * @param start The zero-based location in the array from which to start removing elements. * @param deleteCount The number of elements to remove. + * @returns An array containing the elements that were deleted. */ splice(start: number, deleteCount?: number): T[]; /** @@ -1269,23 +1280,24 @@ interface Array { * @param start The zero-based location in the array from which to start removing elements. * @param deleteCount The number of elements to remove. * @param items Elements to insert into the array in place of the deleted elements. + * @returns An array containing the elements that were deleted. */ splice(start: number, deleteCount: number, ...items: T[]): T[]; /** - * Inserts new elements at the start of an array. - * @param items Elements to insert at the start of the Array. + * Inserts new elements at the start of an array, and returns the new length of the array. + * @param items Elements to insert at the start of the array. */ unshift(...items: T[]): number; /** - * Returns the index of the first occurrence of a value in an array. + * Returns the index of the first occurrence of a value in an array, or -1 if it is not present. * @param searchElement The value to locate in the array. * @param fromIndex The array index at which to begin the search. If fromIndex is omitted, the search starts at index 0. */ indexOf(searchElement: T, fromIndex?: number): number; /** - * Returns the index of the last occurrence of a specified value in an array. + * Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present. * @param searchElement The value to locate in the array. - * @param fromIndex The array index at which to begin the search. If fromIndex is omitted, the search starts at the last index in the array. + * @param fromIndex The array index at which to begin searching backward. If fromIndex is omitted, the search starts at the last index in the array. */ lastIndexOf(searchElement: T, fromIndex?: number): number; /** From 3aeee93161a70698baa0dfc12155da5cc3fd3d80 Mon Sep 17 00:00:00 2001 From: Orta Date: Wed, 16 Dec 2020 15:13:37 +0000 Subject: [PATCH 2/2] Accept baseline changes for new lines from JSDoc changes --- .../reference/destructuringParameterDeclaration4.errors.txt | 2 +- tests/baselines/reference/destructuringTuple.errors.txt | 4 ++-- tests/baselines/reference/promisePermutations.errors.txt | 2 +- tests/baselines/reference/promisePermutations2.errors.txt | 2 +- tests/baselines/reference/promisePermutations3.errors.txt | 4 ++-- tests/baselines/reference/redefineArray.errors.txt | 2 +- tests/cases/fourslash/commentsUnion.ts | 2 +- tests/cases/fourslash/completionListOfGenericSymbol.ts | 2 +- 8 files changed, 10 insertions(+), 10 deletions(-) diff --git a/tests/baselines/reference/destructuringParameterDeclaration4.errors.txt b/tests/baselines/reference/destructuringParameterDeclaration4.errors.txt index d3e198c87149a..e7e55ca0e1a5d 100644 --- a/tests/baselines/reference/destructuringParameterDeclaration4.errors.txt +++ b/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:1403:13: 'Array' is declared here. +!!! related TS2728 /.ts/lib.es5.d.ts:1415: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]]'. diff --git a/tests/baselines/reference/destructuringTuple.errors.txt b/tests/baselines/reference/destructuringTuple.errors.txt index 31ffdac62200a..7b9785db0f198 100644 --- a/tests/baselines/reference/destructuringTuple.errors.txt +++ b/tests/baselines/reference/destructuringTuple.errors.txt @@ -33,8 +33,8 @@ tests/cases/compiler/destructuringTuple.ts(11,60): error TS2769: No overload mat !!! error TS2769: Overload 2 of 3, '(callbackfn: (previousValue: [], currentValue: number, currentIndex: number, array: number[]) => [], initialValue: []): []', gave the following error. !!! error TS2769: Type 'never[]' is not assignable to type '[]'. !!! error TS2769: Target allows only 0 element(s) but source may have more. -!!! related TS6502 /.ts/lib.es5.d.ts:1368:24: The expected type comes from the return type of this signature. -!!! related TS6502 /.ts/lib.es5.d.ts:1374:27: The expected type comes from the return type of this signature. +!!! related TS6502 /.ts/lib.es5.d.ts:1380:24: The expected type comes from the return type of this signature. +!!! related TS6502 /.ts/lib.es5.d.ts:1386:27: The expected type comes from the return type of this signature. ~~ !!! error TS2769: No overload matches this call. !!! error TS2769: Overload 1 of 2, '(...items: ConcatArray[]): never[]', gave the following error. diff --git a/tests/baselines/reference/promisePermutations.errors.txt b/tests/baselines/reference/promisePermutations.errors.txt index 5554fb9afcf7d..bcceb3790cc37 100644 --- a/tests/baselines/reference/promisePermutations.errors.txt +++ b/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' is not assignable to parameter of type '(error: any) => Promise'. !!! error TS2769: Property 'catch' is missing in type 'IPromise' but required in type 'Promise'. -!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here. +!!! related TS2728 /.ts/lib.es5.d.ts:1460: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 diff --git a/tests/baselines/reference/promisePermutations2.errors.txt b/tests/baselines/reference/promisePermutations2.errors.txt index c8b2e09ba0bce..053bc3c1a8751 100644 --- a/tests/baselines/reference/promisePermutations2.errors.txt +++ b/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' is not assignable to parameter of type '(error: any) => Promise'. !!! error TS2345: Property 'catch' is missing in type 'IPromise' but required in type 'Promise'. -!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here. +!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here. var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok var r11: IPromise; diff --git a/tests/baselines/reference/promisePermutations3.errors.txt b/tests/baselines/reference/promisePermutations3.errors.txt index f59d1f678b3ea..3303c1e3a094b 100644 --- a/tests/baselines/reference/promisePermutations3.errors.txt +++ b/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' is not assignable to parameter of type '(error: any) => Promise'. !!! error TS2769: Property 'catch' is missing in type 'IPromise' but required in type 'Promise'. -!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here. +!!! related TS2728 /.ts/lib.es5.d.ts:1460: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 '{ (x: T): IPromise; (x: T, y: T): Promise; }' is not assignable to parameter of type '(value: (x: any) => any) => Promise'. !!! error TS2345: Property 'catch' is missing in type 'IPromise' but required in type 'Promise'. -!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here. +!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here. var s12c = s12.then(testFunction12P, testFunction12, testFunction12); // ok \ No newline at end of file diff --git a/tests/baselines/reference/redefineArray.errors.txt b/tests/baselines/reference/redefineArray.errors.txt index 46d6bd02e864c..e59c0e9e24a1c 100644 --- a/tests/baselines/reference/redefineArray.errors.txt +++ b/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:1399:5: 'isArray' is declared here. \ No newline at end of file +!!! related TS2728 /.ts/lib.es5.d.ts:1411:5: 'isArray' is declared here. \ No newline at end of file diff --git a/tests/cases/fourslash/commentsUnion.ts b/tests/cases/fourslash/commentsUnion.ts index 616da3ea9d201..cee57c7379dfd 100644 --- a/tests/cases/fourslash/commentsUnion.ts +++ b/tests/cases/fourslash/commentsUnion.ts @@ -3,4 +3,4 @@ ////var a: Array | Array; ////a./*1*/length -verify.quickInfoAt("1", "(property) Array.length: number", "Gets or sets the length of the array. This is a number one higher than the highest element defined in an array."); \ No newline at end of file +verify.quickInfoAt("1", "(property) Array.length: number", "Gets or sets the length of the array. This is a number one higher than the highest index in the array."); diff --git a/tests/cases/fourslash/completionListOfGenericSymbol.ts b/tests/cases/fourslash/completionListOfGenericSymbol.ts index 380407d239058..6d17cd06d159d 100644 --- a/tests/cases/fourslash/completionListOfGenericSymbol.ts +++ b/tests/cases/fourslash/completionListOfGenericSymbol.ts @@ -11,7 +11,7 @@ verify.completions({ { name: "length", text: "(property) Array.length: number", - documentation: "Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.", + documentation: "Gets or sets the length of the array. This is a number one higher than the highest index in the array.", kind: "property", kindModifiers: "declare", },