Improve documentation for basic array methods (#41961)

* Improve documentation for basic array methods

* Accept baseline changes for new lines from JSDoc changes

Co-authored-by: Orta <[email protected]>

Author: branpk

src/lib/es5.d.ts

@@ -1199,7 +1199,7 @@ interface ConcatArray<T> {
 
 interface Array<T> {
     /**
-     * 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<T> {
     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>[]): 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>)[]): 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,30 +1272,32 @@ interface Array<T> {
      * 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[];
     /**
      * 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.
      * @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;
     /**

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]]'.

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>[]): never[]', gave the following error.

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: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
 

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: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<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: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 '{ <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: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

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.
+!!! related TS2728 /.ts/lib.es5.d.ts:1411:5: 'isArray' is declared here.

tests/cases/fourslash/commentsUnion.ts

@@ -3,4 +3,4 @@
 ////var a: Array<string> | Array<number>;
 ////a./*1*/length
 
-verify.quickInfoAt("1", "(property) Array<T>.length: number", "Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.");
+verify.quickInfoAt("1", "(property) Array<T>.length: number", "Gets or sets the length of the array. This is a number one higher than the highest index in the array.");

tests/cases/fourslash/completionListOfGenericSymbol.ts

@@ -11,7 +11,7 @@ verify.completions({
         {
             name: "length",
             text: "(property) Array<number>.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",
         },