chore: Improve description of optional arguments in ExpectAPI.md (#8126)

* chore: Improve description of optional arguments in ExpectAPI.md

* Add missing argument toThrowErrorMatchingInlineSnapshot

* Update CHANGELOG.md

* Rewrite snapshotName paragraph and add inlineSnapshot paragraph

CHANGELOG.md

@@ -8,6 +8,7 @@
 
 - `[*]` Remove flow from code base ([#8061](https://github.com/facebook/jest/pull/8061))
 - `[*]` Use property initializer syntax in Jest codebase [#8117](https://github.com/facebook/jest/pull/8117)
+- `[docs]` Improve description of optional arguments in ExpectAPI.md [#8126](https://github.com/facebook/jest/pull/8126)
 - `[*]` Move @types/node to the root package.json [#8129](https://github.com/facebook/jest/pull/8129)
 
 ### Performance

docs/ExpectAPI.md

@@ -745,7 +745,7 @@ test('drink returns expected nth calls', () => {
 
 Note: the nth argument must be positive integer starting from 1.
 
-### `.toBeCloseTo(number, numDigits)`
+### `.toBeCloseTo(number, numDigits?)`
 
 Using exact equality with floating point numbers is a bad idea. Rounding means that intuitive things fail. For example, this test fails:
 
@@ -765,7 +765,7 @@ test('adding works sanely with simple decimals', () => {
 });
 ```
 
-The default for `numDigits` is 2, which has proved to be a good default in most cases.
+The optional `numDigits` argument has default value `2` which means the criterion is `Math.abs(expected - received) < 0.005` (that is, `10 ** -2 / 2`).
 
 ### `.toBeDefined()`
 
@@ -1059,11 +1059,11 @@ describe('toMatchObject applied to arrays', () => {
 });
 ```
 
-### `.toHaveProperty(keyPath, value)`
+### `.toHaveProperty(keyPath, value?)`
 
 Use `.toHaveProperty` to check if property at provided reference `keyPath` exists for an object. For checking deeply nested properties in an object you may use [dot notation](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Property_accessors) or an array containing the keyPath for deep references.
 
-Optionally, you can provide a `value` to check if it's equal to the value present at `keyPath` on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks the equality of all fields.
+You can provide an optional `value` argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the `toEqual` matcher).
 
 The following example contains a `houseForSale` object with nested properties. We are using `toHaveProperty` to check for the existence and values of various properties in the object.
 
@@ -1113,19 +1113,23 @@ test('this house has my desired features', () => {
 });
 ```
 
-### `.toMatchSnapshot(propertyMatchers, snapshotName)`
+### `.toMatchSnapshot(propertyMatchers?, snapshotName?)`
 
 This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information.
 
-The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. Any value will be matched exactly if not provided as a matcher.
+You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
 
-The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test.
+You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
 
 _Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._
 
-### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)`
+### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)`
 
-Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline.
+Ensures that a value matches the most recent snapshot.
+
+You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
+
+Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs.
 
 Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info.
 
@@ -1154,9 +1158,9 @@ describe('the La Croix cans on my desk', () => {
 });
 ```
 
-### `.toThrow(error)`
+### `.toThrow(error?)`
 
-Also under the alias: `.toThrowError(error)`
+Also under the alias: `.toThrowError(error?)`
 
 Use `.toThrow` to test that a function throws when it is called. For example, if we want to test that `drinkFlavor('octopus')` throws, because octopus flavor is too disgusting to drink, we could write:
 
@@ -1168,7 +1172,7 @@ test('throws on octopus', () => {
 });
 ```
 
-To test that a specific error is thrown, you can provide an argument:
+You can provide an optional argument to test that a specific error is thrown:
 
 - regular expression: error message **matches** the pattern
 - string: error message **includes** the substring
@@ -1209,9 +1213,13 @@ test('throws on octopus', () => {
 
 > Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
 
-### `.toThrowErrorMatchingSnapshot()`
+### `.toThrowErrorMatchingSnapshot(snapshotName?)`
+
+Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
 
-Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this:
+You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
+
+For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this:
 
 ```js
 function drinkFlavor(flavor) {
@@ -1242,8 +1250,10 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`;
 
 Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing.
 
-### `.toThrowErrorMatchingInlineSnapshot()`
+### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)`
+
+Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
 
-This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically.
+Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs.
 
 Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info.

website/versioned_docs/version-24.0/ExpectAPI.md

@@ -746,7 +746,7 @@ test('drink returns expected nth calls', () => {
 
 Note: the nth argument must be positive integer starting from 1.
 
-### `.toBeCloseTo(number, numDigits)`
+### `.toBeCloseTo(number, numDigits?)`
 
 Using exact equality with floating point numbers is a bad idea. Rounding means that intuitive things fail. For example, this test fails:
 
@@ -766,7 +766,7 @@ test('adding works sanely with simple decimals', () => {
 });
 ```
 
-The default for `numDigits` is 2, which has proved to be a good default in most cases.
+The optional `numDigits` argument has default value `2` which means the criterion is `Math.abs(expected - received) < 0.005` (that is, `10 ** -2 / 2`).
 
 ### `.toBeDefined()`
 
@@ -1060,11 +1060,11 @@ describe('toMatchObject applied to arrays', () => {
 });
 ```
 
-### `.toHaveProperty(keyPath, value)`
+### `.toHaveProperty(keyPath, value?)`
 
 Use `.toHaveProperty` to check if property at provided reference `keyPath` exists for an object. For checking deeply nested properties in an object you may use [dot notation](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Property_accessors) or an array containing the keyPath for deep references.
 
-Optionally, you can provide a `value` to check if it's equal to the value present at `keyPath` on the target object. This matcher uses 'deep equality' (like `toEqual()`) and recursively checks the equality of all fields.
+You can provide an optional `value` argument to compare the received property value (recursively for all properties of object instances, also known as deep equality, like the `toEqual` matcher).
 
 The following example contains a `houseForSale` object with nested properties. We are using `toHaveProperty` to check for the existence and values of various properties in the object.
 
@@ -1114,19 +1114,23 @@ test('this house has my desired features', () => {
 });
 ```
 
-### `.toMatchSnapshot(propertyMatchers, snapshotName)`
+### `.toMatchSnapshot(propertyMatchers?, snapshotName?)`
 
 This ensures that a value matches the most recent snapshot. Check out [the Snapshot Testing guide](SnapshotTesting.md) for more information.
 
-The optional `propertyMatchers` argument allows you to specify asymmetric matchers which are verified instead of the exact values. Any value will be matched exactly if not provided as a matcher.
+You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
 
-The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test.
+You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
 
 _Note: While snapshot testing is most commonly used with React components, any serializable value can be used as a snapshot._
 
-### `.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)`
+### `.toMatchInlineSnapshot(propertyMatchers?, inlineSnapshot)`
 
-Ensures that a value matches the most recent snapshot. Unlike [`.toMatchSnapshot()`](#tomatchsnapshotpropertymatchers-snapshotname), the snapshots will be written to the current source file, inline.
+Ensures that a value matches the most recent snapshot.
+
+You can provide an optional `propertyMatchers` object argument, which has asymmetric matchers as values of a subset of expected properties, **if** the received value will be an **object** instance. It is like `toMatchObject` with flexible criteria for a subset of properties, followed by a snapshot test as exact criteria for the rest of the properties.
+
+Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs.
 
 Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info.
 
@@ -1155,9 +1159,9 @@ describe('the La Croix cans on my desk', () => {
 });
 ```
 
-### `.toThrow(error)`
+### `.toThrow(error?)`
 
-Also under the alias: `.toThrowError(error)`
+Also under the alias: `.toThrowError(error?)`
 
 Use `.toThrow` to test that a function throws when it is called. For example, if we want to test that `drinkFlavor('octopus')` throws, because octopus flavor is too disgusting to drink, we could write:
 
@@ -1169,7 +1173,7 @@ test('throws on octopus', () => {
 });
 ```
 
-To test that a specific error is thrown, you can provide an argument:
+You can provide an optional argument to test that a specific error is thrown:
 
 - regular expression: error message **matches** the pattern
 - string: error message **includes** the substring
@@ -1210,9 +1214,13 @@ test('throws on octopus', () => {
 
 > Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.
 
-### `.toThrowErrorMatchingSnapshot()`
+### `.toThrowErrorMatchingSnapshot(snapshotName?)`
+
+Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
 
-Use `.toThrowErrorMatchingSnapshot` to test that a function throws an error matching the most recent snapshot when it is called. For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this:
+You can provide an optional `snapshotName` string argument that is appended to the test name. Jest always appends a number at the end of a snapshot key to differentiate snapshots from a single `it` or `test` block. Jest sorts snapshots by key in the corresponding `.snap` file.
+
+For example, let's say you have a `drinkFlavor` function that throws whenever the flavor is `'octopus'`, and is coded like this:
 
 ```js
 function drinkFlavor(flavor) {
@@ -1243,8 +1251,10 @@ exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`;
 
 Check out [React Tree Snapshot Testing](https://jestjs.io/blog/2016/07/27/jest-14.html) for more information on snapshot testing.
 
-### `.toThrowErrorMatchingInlineSnapshot()`
+### `.toThrowErrorMatchingInlineSnapshot(inlineSnapshot)`
+
+Use `.toThrowErrorMatchingInlineSnapshot` to test that a function throws an error matching the most recent snapshot when it is called.
 
-This matcher is much like [`.toThrowErrorMatchingSnapshot`](#tothrowerrormatchingsnapshot), except instead of writing the snapshot value to a `.snap` file, it will be written into the source code automatically.
+Jest adds the `inlineSnapshot` string argument to the matcher in the test file (instead of an external `.snap` file) the first time that the test runs.
 
 Check out the section on [Inline Snapshots](SnapshotTesting.md#inline-snapshots) for more info.