docs: update docs

index.d.ts

@@ -62,24 +62,22 @@ console.log(await getPort({port: portNumbers(3000, 3100)}));
 export function portNumbers(from: number, to: number): Iterable<number>;
 
 /**
-Clear the internal cache of locked ports.
-
-When you want your results to be unaffected by previous calls.
-
-Of course, this carries potential risks as you are disrupting the internal cache.
-
-Therefore, you need to be absolutely certain about this decision.
-
-Example:
+Clear the internal cache of locked ports when you want your results to be unaffected by previous calls.
 
+@example
 ```
 import getPort, {clearLockedPorts} from 'get-port';
 
-// Before using it, clear the cache.
-clearLockedPorts();
-const port = await getPort();
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3000
 
-```
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3001
 
+// If you want your results to be unaffected by previous calls, clear the cache.
+clearLockedPorts();
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3000
+```
  */
 export function clearLockedPorts(): void;

readme.md

@@ -49,9 +49,16 @@ Use the `clearLockedPorts()` to clear the internal cache of locked ports.
 ```js
 import getPort, {clearLockedPorts} from 'get-port';
 
-// Before using it, clear the cache.
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3000
+
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3001
+
+// If you want the results to not be affected by previous calls, clear the cache.
 clearLockedPorts();
-const port = await getPort();
+console.log(await getPort({prot: [3000, 3001, 3002]}));
+//=> 3000
 ```
 
 ## API
@@ -106,7 +113,7 @@ The last port of the range. Must be in the range `1024`...`65535` and must be gr
 
 ### clearLockedPorts
 
-Clear the internal cache of locked ports.
+Clear the internal cache of locked ports when you want your results to be unaffected by previous calls.
 
 ## Beware