update docs for all other methods

docs/_api-inspection/called.md

@@ -3,5 +3,5 @@ title: .called(filter, options)
 navTitle: .called()
 position: 1
 description: |-
-  Returns a Boolean indicating whether any calls to `fetch` matched the given filter
+  Returns a Boolean indicating whether any calls to `fetch` matched the given `filter` and `options`
 ---

docs/_api-inspection/calls.md

@@ -3,5 +3,5 @@ title: .calls(filter, options)
 navTitle: .calls()
 position: 2
 description: |-
-  Returns an array of all calls to fetch matching the given filters. Each call is returned as a `[url, options]` array. If `fetch` was called using a `Request` instance, this will be available as a `request` property on this array.
+  Returns an array of all calls to fetch matching the given `filter` and `options`. Each call is returned as a `[url, options]` array. If `fetch` was called using a `Request` instance, the `url` and `options` will be inferred from it, and the original `Request` will be available as a `request` property on this array.
 ---

docs/_api-inspection/done.md

@@ -12,7 +12,7 @@ parameters:
         - undefined
         - true
         content: |-
-          Runs over all calls matched by `fetch`
+          Returns true if all routes have been called the expected number of times
       - name: routeIdentifier
         types:
           - String|RegExp|function
@@ -21,8 +21,8 @@ parameters:
           - If it's a named route, the identifier is the route's name
           - If the route is unnamed, the identifier is the `matcher` passed in to `.mock()`
 
-          All calls that were handled by the route with the given identifier will be retrieved
+          Returns true if the routes specified by the identifier has been called the expected number of times
 content_markdown: |-
-  If several routes have the same matcher/url, but use [mocking options](#apimockingmock_options), the recommended way to handle this is to name each route and filter using those names
-  {: .info}
+  If several routes have the same matcher/url, but use [mocking options](#apimockingmock_options), the recommended way to handle this is to [name each route](#api-mockingmock_options) and filter using those names
+  
 ---

docs/_api-inspection/fundamentals.md

@@ -0,0 +1,88 @@
+---
+title: "Inspection fundamentals"
+position: 0
+description: |-
+  `fetch-mock`'s inspection methods allow information about how `fetch` was called to be retrieved after your application code has run. Most inspection methods take two arguments — `filter` and `options` — which allow individual, or groups of, `fetch` calls to be extracted and examined.
+parameters:
+  - name: filter
+    content: |-
+      Filter calls to `fetch` using one of the following criteria:
+    options:
+      - types:
+        - undefined
+        content: |-
+          Retrieve all calls made to `fetch`
+      - types:
+        - true
+        content: |-
+          Retrieve all calls to `fetch` matched by some route defined by `fetch-mock`. `fetchMock.MATCHED` is an alias for `true` and may be used to make tests more readable
+        examples:
+          - |-
+            const {MATCHED, fetchMock} = require('fetch-mock');
+            ...
+            fetchMock.calls(MATCHED)
+      - types:
+        - false
+        content: |-
+          Retrieves all calls to `fetch` not matched by a route (i.e. those handled by `catch()`, `spy()` or the `fallbackToNetwork` option). `fetchMock.UNMATCHED` is an alias for `false` and may be used to make tests more readable
+        examples:
+          - |-
+            const {UNMATCHED, fetchMock} = require('fetch-mock');
+            ...
+            fetchMock.calls(UNMATCHED)
+      - name: routeIdentifier
+        types:
+          - String|RegExp|function
+        content: |-
+          All routes have an identifier:
+          - If it's a [named route](#api-mockingmock_options), the identifier is the route's `name`
+          - If the route is unnamed, the identifier is the value of the `matcher` argument that was passed in to `.mock()`
+
+          All calls that were handled by the route with the given identifier will be retrieved
+      - name: matcher
+        types:
+          - String|RegExp|function
+        content: |-
+          Any matcher compatible with the [mocking api](#api-mockingmock_matcher) can be passed in to filter the calls arbitrarily. The matcher will be executed using exactly the same rules as the mocking api
+  - name: options
+    types:
+      - Object
+      - String
+    content: |-
+      Either an object compatible with the [mocking api](#api-mockingmock_options) or a string specifying a http method to filter by. This will be used to filter the list of calls further
+content_markdown: |-
+  
+  The filtering API is powerful, but potentially confusing. If in doubt, [add a `name` to your route](#api-mockingmock_options), and pass that name in to retrieve exactly the calls you want.
+
+  #### A note on Regular Expression and Function matchers
+  To retrieve calls handled by a route with a `RegExp` or `function` matcher, use a reference to the exact `RegExp`|`function` you used in your mock, e.g.
+
+  ```javascript
+  const matcherRX = /user\/biff/
+  fm.mock(matcherRX, 200)
+  ...
+  fm.called(matcherRX)
+  ```
+
+  not
+
+  ```javascript
+  fm.mock(/user\/biff/, 200)
+  ...
+  fm.called(/user\/biff/)
+  ```
+
+  The second example _will_ retrieve the expected calls in simple test scenarios because if no routes match using the identifier the `RegExp` will be executed as a `RegExp` matcher. But in more complex scenarios where e.g. there are several routes handling similar paths, it might retrieve calls that were actually handled by different, similar route e.g.
+
+  ```javascript
+  const matcherRX = /user\/biff/
+  fm
+    .mock('end:user/biff')
+    .mock(matcherRX, 200)
+  ...
+  // this will retrieve calls handled by either route
+  fm.called(/user\/biff/)
+  // this will retrieve only calls handeld by the second route
+  fm.called(/user\/biff/)
+  ```
+---

docs/_api-inspection/lastCall.md

@@ -3,5 +3,5 @@ title: .lastCall(filter, options)
 navTitle: .lastCall()
 position: 3
 description: |-
-  Returns the arguments for the last call to `fetch` matching the given filter
+  Returns the arguments for the last call to `fetch` matching the given `filter` and `options`. The call is returned as a `[url, options]` array. If `fetch` was called using a `Request` instance, the `url` and `options` will be inferred from it, and the original `Request` will be available as a `request` property on this array.
 ---

docs/_api-inspection/lastOptions.md

@@ -3,5 +3,5 @@ title: .lastOptions(filter, options)
 navTitle: .lastOptions()
 position: 5
 description: |-
-  Returns the options for the call to `fetch` matching the given filter. If `fetch` was last called using a `Request` instance, a set of `options` inferred from the `Request` will be returned
+  Returns the options for the call to `fetch` matching the given `filter` and `options`. If `fetch` was last called using a `Request` instance, a set of `options` inferred from the `Request` will be returned
 ---

docs/_api-inspection/lastUrl.md

@@ -3,5 +3,5 @@ title: .lastUrl(filter, options)
 navTitle: .lastUrl()
 position: 4
 description: |-
-  Returns the url for the last call to `fetch` matching the given filter. If `fetch` was last called using a `Request` instance, the url will be extracted from this
+  Returns the url for the last call to `fetch` matching the given `filter` and `options`. If `fetch` was last called using a `Request` instance, the url will be inferred from this
 ---

docs/_api-lifecycle/flush.md

@@ -7,6 +7,5 @@ description: |-
 content_markdown: |-
   Useful for testing code that uses `fetch` but doesn't return a promise.
 
-  Pass in `true` to wait for all body parsing methods (`res.json()`, `res.text()`, etc.) to resolve too.
-  {: .info}
+  If `waitForBody` is `true`, the promise will wait for all body parsing methods (`res.json()`, `res.text()`, etc.) to resolve too.
 ---

docs/_api-lifecycle/resetHistory.md

@@ -3,4 +3,6 @@ title: .resetHistory()
 position: 4
 description: |-
   Clears all data recorded for `fetch()`'s calls. It _will not_ restore fetch to its default implementation
+content_markdown: |-
+  `resetHistory()` is bound to fetchMock, and can be used directly as a callback e.g. `afterEach(fetchMock.resetHistory)` will work just fine. There is no need for `afterEach(function () {fetchMock.resetHistory()})`
 ---

docs/_api-lifecycle/restore_reset.md

@@ -3,18 +3,7 @@ title: .restore(), .reset()
 navTitle: .restore(), .reset()
 position: 3
 description: |-
-  Restores `fetch()` to its unstubbed state and clears all data recorded for its calls. `reset()` is an alias for `restore()`
+  Resets `fetch()` to its unstubbed state and clears all data recorded for its calls. `restore()` is an alias for `reset()`
+content_markdown: |-
+  Both methods are bound to fetchMock, and can be used directly as callbacks e.g. `afterEach(fetchMock.reset)` will work just fine. There is no need for `afterEach(function () {fetchMock.reset()})`
 ---
-
-#### ``
-
-Chainable method that .
-
-#### `resetHistory()`
-
-Chainable method that clears all data recorded for `fetch()`'s calls. _It will not restore fetch to its default implementation_
-
-_Note that `restore()`, `reset()` and `resetHistory()` are all bound to fetchMock, and can be used directly as callbacks e.g. `afterEach(fetchMock.reset)` will work just fine. There is no need for `afterEach(function () {fetchMock.reset()})`_
-
-#### `flush()`
-

docs/_api-lifecycle/sandbox.md

@@ -2,7 +2,7 @@
 title: ".sandbox()"
 position: 1.0
 description: |-
-  Returns a drop-in mock for fetch which can be passed to other mocking libraries. It implements the full fetch-mock api and maintains its own state independent of other instances, so tests can be run in parallel.
+  eturns a function that can be used as a drop-in replacement for `fetch`. Pass this into your mocking library of choice. The function returned by `sandbox()` has all the methods of `fetch-mock` exposed on it and maintains its own state independent of other instances, so tests can be run in parallel.
 left_code_blocks:
   - code_block: |-
       fetchMock

docs/_api-mocking/spy.md

@@ -6,6 +6,5 @@ description: |-
   Records call history while passing each call on to `fetch` to be handled by the network
 parentMethodGroup: mocking
 content_markdown: |-
-   To use `.spy()` on a sandboxed `fetchMock`, `fetchMock.config.fetch` must be set to a reference to the `fetch` implementation you use in your code.
-   
+   To use `.spy()` on a sandboxed `fetchMock`, `fetchMock.config.fetch` must be set to the same `fetch` implementation used in your application. [See how to configure this](#usagecustom-classes)
 ---