Improve docs for ky.stop

readme.md

@@ -256,7 +256,9 @@ Default: `[]`
 
 This hook enables you to modify the request right before retry. Ky will make no further changes to the request after this. The hook function receives an object with the normalized request and options, an error instance, and the retry count. You could, for example, modify `request.headers` here.
 
-If the request received a response, it will be available at `error.response`. Be aware that some types of errors, such as network errors, inherently mean that a response was not received.
+If the request received a response, `error` will be an `HTTPError` and the `Response` object will be available at `error.response`. Be aware that some types of errors, such as network errors, inherently mean that a response was not received. In that case, `error` will not be an instance of `HTTPError`, though.
+
+You can prevent Ky from retrying the request by throwing `error`. Ky will not handle it in any way, this error will be propagated to the request initiator. The rest of the `beforeRetry` hooks will not be called if you `throw error`. Alternatively, you can return the [`ky.stop`](#ky.stop) symbol to do the same thing but without throwing (this has some limitations, see `ky.stop` docs for details).
 
 ```js
 import ky from 'ky';
@@ -468,22 +470,29 @@ The error thrown when the request times out.
 
 A `Symbol` that can be returned by a `beforeRetry` hook to stop the retry. This will also short circuit the remaining `beforeRetry` hooks.
 
+Note: This aborts _successfully_ and Ky will return with an `undefined` response. If you use `ky.stop`, be sure to check for a response first before accessing any properties on it or use [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining). It is also incompatible with body methods, such as `.json()` or `.text()`, because there is no response to parse. In general, we recommend to `throw error` instead of `return ky.stop`, as that will abort _unsuccesfully_ and Ky will throw, which avoids these limitations.
+
+A valid use case for `ky.stop` is to prevent retries when making requests for side effects, where returned data is not important. For example, logging client activity to the server.
+
 ```js
 import ky from 'ky';
 
 (async () => {
-	await ky('https://example.com', {
+	const options = {
 		hooks: {
 			beforeRetry: [
 				async ({request, options, error, retryCount}) => {
-					const shouldStopRetry = await ky('https://example.com/api');
-					if (shouldStopRetry) {
-						return ky.stop;
-					}
+					const token = await ky('https://example.com/refresh-token');
+					request.headers.set('Authorization', `token ${token}`);
 				}
 			]
 		}
-	});
+	}
+
+	await ky.post('https://example.com', options);
+
+	// Using .text() or other body methods is not suppported
+	const text = await ky('https://example.com', options).text();
 })();
 ```