8000 Improve documentation for basic array methods (#41961) · typescript-bot/TypeScript@822962e · GitHub
[go: up one dir, main page]
Skip to content

Commit 822962e

Browse files
branpkorta
branpk
and
orta
authored
Improve documentation for basic array methods (microsoft#41961)
* Improve documentation for basic array methods * Accept baseline changes for new lines from JSDoc changes Co-authored-by: Orta <git@orta.io>
1 parent 562237d commit 822962e

9 files changed

+39
-27
lines changed

‎src/lib/es5.d.ts

Lines changed: 29 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1199,7 +1199,7 @@ interface ConcatArray<T> {
11991199

12001200
interface Array<T> {
12011201
/**
1202-
* Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.
1202+
* Gets or sets the length of the array. This is a number one higher than the highest index in the array.
12031203
*/
12041204
length: number;
12051205
/**
@@ -1212,44 +1212,54 @@ interface Array<T> {
12121212
toLocaleString(): string;
12131213
/**
12141214
* Removes the last element from an array and returns it.
1215+
* If the array is empty, undefined is returned and the array is not modified.
12151216
*/
12161217
pop(): T | undefined;
12171218
/**
1218-
* Appends new elements to an array, and returns the new length of the array.
1219-
* @param items New elements of the Array.
1219+
* Appends new elements to the end of an array, and returns the new length of the array.
1220+
* @param items New elements to add to the array.
12201221
*/
12211222
push(...items: T[]): number;
12221223
/**
12231224
* Combines two or more arrays.
1224-
* @param items Additional items to add to the end of array1.
1225+
* This method returns a new array without modifying any existing arrays.
1226+
* @param items Additional arrays and/or items to add to the end of the array.
12251227
*/
12261228
concat(...items: ConcatArray<T>[]): T[];
12271229
/**
12281230
* Combines two or more arrays.
1229-
* @param items Additional items to add to the end of array1.
1231+
* This method returns a new array without modifying any existing arrays.
1232+
* @param items Additional arrays and/or items to add to the end of the array.
12301233
*/
12311234
concat(...items: (T | ConcatArray<T>)[]): T[];
12321235
/**
1233-
* Adds all the elements of an array separated by the specified separator string.
1234-
* @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.
1236+
* Adds all the elements of an array into a string, separated by the specified separator string.
1237+
* @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.
12351238
*/
12361239
join(separator?: string): string;
12371240
/**
1238-
* Reverses the elements in an Array.
1241+
* Reverses the elements in an array in place.
1242+
* This method mutates the array and returns a reference to the same array.
12391243
*/
12401244
reverse( 8000 ): T[];
12411245
/**
12421246
* Removes the first element from an array and returns it.
1247+
* If the array is empty, undefined is returned and the array is not modified.
12431248
*/
12441249
shift(): T | undefined;
12451250
/**
1246-
* Returns a section of an array.
1247-
* @param start The beginning of the specified portion of the array.
1248-
* @param end The end of the specified portion of the array. This is exclusive of the element at the index 'end'.
1251+
* Returns a copy of a section of an array.
1252+
* For both start and end, a negative index can be used to indicate an offset from the end of the array.
1253+
* For example, -2 refers to the second to last element of the array.
1254+
* @param start The beginning index of the specified portion of the array.
1255+
* If start is undefined, then the slice begins at index 0.
1256+
* @param end The end index of the specified portion of the array. This is exclusive of the element at the index 'end'.
1257+
* If end is undefined, then the slice extends to the end of the array.
12491258
*/
12501259
slice(start?: number, end?: number): T[];
12511260
/**
1252-
* Sorts an array.
1261+
* Sorts an array in place.
1262+
* This method mutates the array and returns a reference to the same array.
12531263
* @param compareFn Function used to determine the order of the elements. It is expected to return
12541264
* a negative value if first argument is less than second argument, zero if they're equal and a positive
12551265
* value otherwise. If omitted, the elements are sorted in ascending, ASCII character order.
@@ -1262,30 +1272,32 @@ interface Array<T> {
12621272
* Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
12631273
* @param start The zero-based location in the array from which to start removing elements.
12641274
* @param deleteCount The number of elements to remove.
1275+
* @returns An array containing the elements that were deleted.
12651276
*/
12661277
splice(start: number, deleteCount?: number): T[];
12671278
/**
12681279
* Removes elements from an array and, if necessary, inserts new elements in their place, returning the deleted elements.
12691280
* @param start The zero-based location in the array from which to start removing elements.
12701281
* @param deleteCount The number of elements to remove.
12711282
* @param items Elements to insert into the array in place of the deleted elements.
1283+
* @returns An array containing the elements that were deleted.
12721284
*/
12731285
splice(start: number, deleteCount: number, ...items: T[]): T[];
12741286
/**
1275-
* Inserts new elements at the start of an array.
1276-
* @param items Elements to insert at the start of the Array.
1287+
* Inserts new elements at the start of an array, and returns the new length of the array.
1288+
* @param items Elements to insert at the start of the array.
12771289
*/
12781290
unshift(...items: T[]): number;
12791291
/**
1280-
* Returns the index of the first occurrence of a value in an array.
1292+
* Returns the index of the first occurrence of a value in an array, or -1 if it is not present.
12811293
* @param searchElement The value to locate in the array.
12821294
* @param fromIndex The array index at which to begin the search. If fromIndex is omitted, the search starts at index 0.
12831295
*/
12841296
indexOf(searchElement: T, fromIndex?: number): number;
12851297
/**
1286-
* Returns the index of the last occurrence of a specified value in an array.
1298+
* Returns the index of the last occurrence of a specified value in an array, or -1 if it is not present.
12871299
* @param searchElement The value to locate in the array.
1288-
* @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.
1300+
* @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.
12891301
*/
12901302
lastIndexOf(searchElement: T, fromIndex?: number): number;
12911303
/**

‎tests/baselines/reference/destructuringParameterDeclaration4.errors.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ tests/cases/conformance/es6/destructuring/destructuringParameterDeclaration4.ts(
4141
a1(...array2); // Error parameter type is (number|string)[]
4242
~~~~~~
4343
!!! error TS2552: Cannot find name 'array2'. Did you mean 'Array'?
44-
!!! related TS2728 /.ts/lib.es5.d.ts:1403:13: 'Array' is declared here.
44+
!!! related TS2728 /.ts/lib.es5.d.ts:1415:13: 'Array' is declared here.
4545
a5([1, 2, "string", false, true]); // Error, parameter type is [any, any, [[any]]]
4646
~~~~~~~~
4747
!!! error TS2322: Type 'string' is not assignable to type '[[any]]'.

‎tests/baselines/reference/destructuringTuple.errors.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@ tests/cases/compiler/destructuringTuple.ts(11,60): error TS2769: No overload mat
3333
!!! error TS2769: Overload 2 of 3, '(callbackfn: (previousValue: [], currentValue: number, currentIndex: number, array: number[]) => [], initialValue: []): []', gave the following error.
3434
!!! error TS2769: Type 'never[]' is not assignable to type '[]'.
3535
!!! error TS2769: Target allows only 0 element(s) but source may have more.
36-
!!! related TS6502 /.ts/lib.es5.d.ts:1368:24: The expected type comes from the return type of this signature.
37-
!!! related TS6502 /.ts/lib.es5.d.ts:1374:27: The expected type comes from the return type of this signature.
36+
!!! related TS6502 /.ts/lib.es5.d.ts:1380:24: The expected type comes from the return type of this signature.
37+
!!! related TS6502 /.ts/lib.es5.d.ts:1386:27: The expected type comes from the return type of this signature.
3838
~~
3939
!!! error TS2769: No overload matches this call.
4040
!!! error TS2769: Overload 1 of 2, '(...items: ConcatArray<never>[]): never[]', gave the following error.

‎tests/baselines/reference/promisePermutations.errors.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -447,7 +447,7 @@ tests/cases/compiler/promisePermutations.ts(160,21): error TS2769: No overload m
447447
!!! error TS2769: The last overload gave the following error.
448448
!!! error TS2769: Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
449449
!!! error TS2769: Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
450-
!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here.
450+
!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here.
451451
!!! related TS2771 tests/cases/compiler/promisePermutations.ts:5:5: The last overload is declared here.
452452
var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
453453

‎tests/baselines/reference/promisePermutations2.errors.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -351,7 +351,7 @@ tests/cases/compiler/promisePermutations2.ts(159,21): error TS2345: Argument of
351351
~~~~~~~~~
352352
!!! error TS2345: Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
353353
!!! error TS2345: Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
354-
!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here.
354+
!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here.
355355
var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
356356

357357
var r11: IPromise<number>;

‎tests/baselines/reference/promisePermutations3.errors.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -398,7 +398,7 @@ tests/cases/compiler/promisePermutations3.ts(165,21): error TS2345: Argument of
398398
!!! error TS2769: The last overload gave the following error.
399399
!!! error TS2769: Argument of type '(x: any) => IPromise<string>' is not assignable to parameter of type '(error: any) => Promise<number>'.
400400
!!! error TS2769: Property 'catch' is missing in type 'IPromise<string>' but required in type 'Promise<number>'.
401-
!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here.
401+
!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here.
402402
!!! related TS2771 tests/cases/compiler/promisePermutations3.ts:7:5: The last overload is declared here.
403403
var s10g = s10.then(testFunctionP, nIPromise, sIPromise).then(sPromise, sIPromise, sIPromise); // ok
404404

@@ -445,5 +445,5 @@ tests/cases/compiler/promisePermutations3.ts(165,21): error TS2345: Argument of
445445
~~~~~~~~~~~~~~~
446446
!!! 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>'.
447447
!!! error TS2345: Property 'catch' is missing in type 'IPromise<any>' but required in type 'Promise<unknown>'.
448-
!!! related TS2728 /.ts/lib.es5.d.ts:1448:5: 'catch' is declared here.
448+
!!! related TS2728 /.ts/lib.es5.d.ts:1460:5: 'catch' is declared here.
449449
var s12c = s12.then(testFunction12P, testFunction12, testFunction12); // ok

‎tests/baselines/reference/redefineArray.errors.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ tests/cases/compiler/redefineArray.ts(1,1): error TS2741: Property 'isArray' is
55
Array = function (n:number, s:string) {return n;};
66
~~~~~
77
!!! error TS2741: Property 'isArray' is missing in type '(n: number, s: string) => number' but required in type 'ArrayConstructor'.
8-
!!! related TS2728 /.ts/lib.es5.d.ts:1399:5: 'isArray' is declared here.
8+
!!! related TS2728 /.ts/lib.es5.d.ts:1411:5: 'isArray' is declared here.

‎tests/cases/fourslash/commentsUnion.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,4 @@
33
////var a: Array<string> 9BF1 | Array<number>;
44
////a./*1*/length
55

6-
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.");
6+
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ verify.completions({
1111
{
1212
name: "length",
1313
text: "(property) Array<number>.length: number",
14-
documentation: "Gets or sets the length of the array. This is a number one higher than the highest element defined in an array.",
14+
documentation: "Gets or sets the length of the array. This is a number one higher than the highest index in the array.",
1515
kind: "property",
1616
kindModifiers: "declare",
1717
},

0 commit comments

Comments
 (0)
0