Improve docs for calculateDelay option

Fixes #2415

Author: sindresorhus

documentation/7-retry.md

@@ -127,7 +127,8 @@ interface RetryObject {
 The function used to calculate the delay before the next request is made. Returning `0` cancels the retry.
 
 **Note:**
-> - This function is responsible for the entire retry mechanism, including the `limit` property. To support this, you need to check if `computedValue` is different than `0`.
+> - When you provide this function, you take full control of the retry logic. The `limit` option is not automatically enforced - it's your responsibility to check `attemptCount` or respect when `computedValue` is `0`.
+> - The `computedValue` parameter contains the default retry delay calculation, which is `0` when the limit is exceeded or the error is not retryable. To maintain default retry behavior while customizing delays, check if `computedValue === 0` and return `0` to stop retrying.
 
 **Tip:**
 > - This is especially useful when you want to scale down the computed value.
@@ -137,7 +138,15 @@ import got from 'got';
 
 await got('https://httpbin.org/anything', {
 	retry: {
+		limit: 3,
 		calculateDelay: ({computedValue}) => {
+			// When computedValue is 0, the default logic says don't retry
+			// (limit exceeded, non-retryable error, etc.)
+			if (computedValue === 0) {
+				return 0;
+			}
+
+			// Scale down the delay
 			return computedValue / 10;
 		}
 	}

source/core/options.ts

@@ -388,6 +388,8 @@ Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.ra
 The `calculateDelay` property is a `function` that receives an object with `attemptCount`, `retryOptions`, `error` and `computedValue` properties for current retry count, the retry options, error and default computed value.
 The function must return a delay in milliseconds (or a Promise resolving with it) (`0` return value cancels retry).
 
+__Note:__ When you provide `calculateDelay`, you take full control of retry decisions. The `limit` option is not automatically enforced - you must check `attemptCount` yourself or return `0` when `computedValue` is `0` to respect the default retry logic.
+
 By default, it retries *only* on the specified methods, status codes, and on these network errors:
 - `ETIMEDOUT`: One of the [timeout](#timeout) limits were reached.
 - `ECONNRESET`: Connection was forcibly closed by a peer.
@@ -2080,6 +2082,8 @@ export default class Options {
 	The `calculateDelay` property is a `function` that receives an object with `attemptCount`, `retryOptions`, `error` and `computedValue` properties for current retry count, the retry options, error and default computed value.
 	The function must return a delay in milliseconds (or a Promise resolving with it) (`0` return value cancels retry).
 
+	__Note:__ When you provide `calculateDelay`, you take full control of retry decisions. The `limit` option is not automatically enforced - you must check `attemptCount` yourself or return `0` when `computedValue` is `0` to respect the default retry logic.
+
 	By default, it retries *only* on the specified methods, status codes, and on these network errors:
 
 	- `ETIMEDOUT`: One of the [timeout](#timeout) limits were reached.