Add more examples to docs for BaseCache.delete()

2 files changed, 32 insertions, 8 deletions

diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 9d0ec9c..5ceefb5 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -143,19 +143,27 @@ Or specify a maximum staleness value you are willing to accept:
 session = CachedSession(stale_while_revalidate=timedelta(minutes=5))
 ```
 
-## Removing Expired Responses
+## Removing Responses
+For better read performance, expired responses won't be removed immediately by default.
+Instead, they will be replaced the next time they are requested.
 
+You can manually delete responses according to various conditions, and some backends support
+automatic removal.
+
+(manual_removal)=
 ### Manual Removal
-For better read performance, expired responses won't be removed immediately, but will be removed
-(or replaced) the next time they are requested.
 
-To manually clear all expired responses, use
-{py:meth}`.BaseCache.remove`:
+To delete **all** cached responses, use {py:meth}`.BaseCache.clear`:
+```python
+>>> session.cache.clear()
+```
+
+To delete expired responses, use {py:meth}`.BaseCache.delete`:
 ```python
->>> session.cache.remove(expired=True)
+>>> session.cache.delete(expired=True)
 ```
 
-Or, if you are using {py:func}`.install_cache`:
+Or, if you have patched ``requests`` using {py:func}`.install_cache`:
 ```python
 >>> requests_cache.remove_expired_responses()
 ```
@@ -163,7 +171,7 @@ Or, if you are using {py:func}`.install_cache`:
 You can also remove responses older than a certain time:
 ```python
 # Remove responses older than 7 days
-session.cache.remove(older_than=timedelta(days=7))
+session.cache.delete(older_than=timedelta(days=7))
 ```
 
 Or apply a new expiration value to previously cached responses:
@@ -172,6 +180,18 @@ Or apply a new expiration value to previously cached responses:
 >>> session.cache.reset_expiration(timedelta(days=30))
 ```
 
+Finally, you can delete responses matching specific requests or {ref}`cache keys <custom-matching>`:
+```python
+>>> from requests import Request
+>>> request_1 = Request('GET', 'https://httpbin.org/get')
+>>> request_2 = Request('GET', 'https://httpbin.org/get', params={'key': 'value'})
+>>> session.cache.delete(requests=[request_1, request_2])
+```
+
+```python
+>>> session.cache.delete('e25f7e6326966e82')
+```
+
 (ttl)=
 ### Automatic Removal
 The following backends have native TTL support, which can be used to automatically remove expired
diff --git a/docs/user_guide/inspection.md b/docs/user_guide/inspection.md
index 98db7e6..873f6a3 100644
--- a/docs/user_guide/inspection.md
+++ b/docs/user_guide/inspection.md
@@ -75,6 +75,10 @@ Get keys for **only** expired responses:
 >>> keys = [response.cache_key for response in expired_responses]
 ```
 
+### Deleting responses
+Use {py:meth}`.BaseCache.delete` to manually delete responses. See {ref}`manual_removal` for
+examples.
+
 ### Response URLs
 You can use {py:meth}`.BaseCache.urls` to see all URLs currently in the cache:
 ```python