Add JSDoc and update readme

README.md

@@ -129,3 +129,100 @@ declare global {
   }
 }
 ```
+
+## Matchers
+
+### Asymmetric Matchers
+
+<table>
+<tr>
+<th>Name</th><th>Description</th><th>Example</th>
+</tr>
+<tr>
+<td>
+
+`exactly`
+
+</td>
+<td>
+
+Uses `Object.is` to ensure referential equality in situations where deep equality would typically be used.
+
+</td>
+<td>
+
+```ts
+expect(mock).toBeCalledWith(expect.exactly(reference));
+```
+
+</td>
+</tr>
+</table>
+
+### Symmetric Matchers
+
+<table>
+<tr>
+<th>Name</th><th>Description</th><th>Example</th>
+</tr>
+<tr>
+<td>
+
+`toBeCalledWithContext`/`toHaveBeenCalledWithContext`
+
+</td>
+<td>
+
+Assert a function has been called with a specific context (`this`).
+
+</td>
+<td>
+
+```ts
+expect(mock).toBeCalledWithContext(expectedContext);
+expect(mock).toHaveBeenCalledWithContext(expectedContext);
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+`lastCalledWithContext`/`toHaveBeenLastCalledWithContext`
+
+</td>
+<td>
+
+Assert the last call of a function was with a specific context (`this`).
+
+</td>
+<td>
+
+```ts
+expect(mock).lastCalledWithContext(expectedContext);
+expect(mock).toHaveBeenLastCalledWithContext(expectedContext);
+```
+
+</td>
+</tr>
+<tr>
+<td>
+
+`nthCalledWithContext`/`toHaveBeenNthCalledWithContext`
+
+</td>
+<td>
+
+Assert the Nth call of a function was with a specific context (`this`).
+
+</td>
+<td>
+
+```ts
+expect(mock).lastCalledWithContext(expectedContext);
+expect(mock).toHaveBeenLastCalledWithContext(expectedContext);
+```
+
+</td>
+</tr>
+</table>

src/asymmetricMatchers/exactly.ts

@@ -2,6 +2,19 @@ import type { MatcherFunction } from "expect";
 import type { MatcherHintOptions } from "jest-matcher-utils";
 import type { AsymmetricMatcher } from "../utils/types";
 
+/**
+ * Matches against the provided value using `Object.is`.
+ * You can use it inside "deep equal" matchers like `toBeCalledWith` to ensure that only the correct reference will be allowed.
+ * @example
+ * const fn = jest.fn();
+ * const ref = {};
+ *
+ * fn(ref);
+ *
+ * expect(fn).toBeCalledWith({})
+ * expect(fn).not.toBeCalledWith(expect.exactly({}))
+ * expect(fn).toBeCalledWith(expect.exactly(ref))
+ */
 export const exactly: MatcherFunction<[expected: unknown]> = function (
   received,
   expected,
@@ -38,6 +51,19 @@ export const exactly: MatcherFunction<[expected: unknown]> = function (
 
 declare module "./index" {
   export interface AsymmetricMixNMatchers {
+    /**
+     * Matches against the provided value using `Object.is`.
+     * You can use it inside "deep equal" matchers like `toBeCalledWith` to ensure that only the correct reference will be allowed.
+     * @example
+     * const fn = jest.fn();
+     * const ref = {};
+     *
+     * fn(ref);
+     *
+     * expect(fn).toBeCalledWith({})
+     * expect(fn).not.toBeCalledWith(expect.exactly({}))
+     * expect(fn).toBeCalledWith(expect.exactly(ref))
+     */
     exactly<E>(expected: E): AsymmetricMatcher;
   }
 }

src/matchers/context.ts

@@ -408,39 +408,100 @@ const createNthCalledWithContextMatcher = (
     };
   };
 
+/**
+ * Ensure a mock function is called with a specific context (`this`)
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const toBeCalledWithContext = createToBeCalledWithContextMatcher(
   "toBeCalledWithContext",
 );
 
+/**
+ * Ensure a mock function is called with a specific context (`this`)
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const toHaveBeenCalledWithContext = createToBeCalledWithContextMatcher(
   "toHaveBeenCalledWithContext",
 );
 
+/**
+ * Ensure the last call to a mock function was provided a specific context (`this`)
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const lastCalledWithContext = createLastCalledWithContextMatcher(
   "lastCalledWithContext",
 );
 
+/**
+ * Ensure the last call to a mock function was provided a specific context (`this`)
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const toHaveBeenLastCalledWithContext =
   createLastCalledWithContextMatcher("toHaveBeenLastCalledWithContext");
 
+/**
+ * Ensure that a mock function was called with a specific context on an Nth call.
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const nthCalledWithContext = createNthCalledWithContextMatcher(
   "nthCalledWithContext",
 );
 
+/**
+ * Ensure that a mock function was called with a specific context on an Nth call.
+ *
+ * Optionally you can provide a type for the expected context via a generic.
+ */
 export const toHaveBeenNthCalledWithContext = createNthCalledWithContextMatcher(
   "toHaveBeenNthCalledWithContext",
 );
 
 declare module "./index" {
   // eslint-disable-next-line @typescript-eslint/no-empty-interface
   export interface MixNMatchers<R> {
+    /**
+     * Ensure a mock function is called with a specific context (`this`)
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     toBeCalledWithContext<E>(expected: E): R;
+    /**
+     * Ensure a mock function is called with a specific context (`this`)
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     toHaveBeenCalledWithContext<E>(expected: E): R;
 
+    /**
+     * Ensure the last call to a mock function was provided a specific context (`this`)
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     lastCalledWithContext<E>(expected: E): R;
+    /**
+     * Ensure the last call to a mock function was provided a specific context (`this`)
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     toHaveBeenLastCalledWithContext<E>(expected: E): R;
 
+    /**
+     * Ensure that a mock function was called with a specific context on an Nth call.
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     nthCalledWithContext<E>(n: number, expected: E): R;
+
+    /**
+     * Ensure that a mock function was called with a specific context on an Nth call.
+     *
+     * Optionally you can provide a type for the expected context via a generic.
+     */
     toHaveBeenNthCalledWithContext<E>(n: number, expected: E): R;
   }
 }