Merge pull request #545 from JWCook/refresh

Add additional revalidation conditions, and new keyword arguments for request() and send()

3 files changed, 9 insertions, 9 deletions

diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
index e3b9424..47eb5d4 100644
--- a/docs/user_guide/compatibility.md
+++ b/docs/user_guide/compatibility.md
@@ -1,4 +1,3 @@
-<!-- TODO: Fix relative links -->
 (compatibility)=
 # {fa}`plus-square` Usage with other requests-based libraries
 This library works by patching and/or extending {py:class}`requests.Session`. Many other libraries
diff --git a/docs/user_guide/expiration.md b/docs/user_guide/expiration.md
index 3113604..ef0e6b3 100644
--- a/docs/user_guide/expiration.md
+++ b/docs/user_guide/expiration.md
@@ -113,8 +113,7 @@ Or, when using patching:
 >>> requests_cache.remove_expired_responses()
 ```
 
-You can also apply a different `expire_after` to previously cached responses, which will
-revalidate the cache with the new expiration time:
+You can also apply a new `expire_after` value to previously cached responses:
 ```python
 >>> session.remove_expired_responses(expire_after=timedelta(days=30))
 ```
diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
index f4ad18d..ecc95c1 100644
--- a/docs/user_guide/headers.md
+++ b/docs/user_guide/headers.md
@@ -47,15 +47,17 @@ The following headers are currently supported:
 
 **Request headers:**
 - `Cache-Control: max-age`: Used as the expiration time in seconds
-- `Cache-Control: no-cache`: Skip reading from the cache
+- `Cache-Control: no-cache`: Revalidate with the server before using a cached response
 - `Cache-Control: no-store`: Skip reading from and writing to the cache
-- `If-None-Match`: Automatically added if an `ETag` is available
-- `If-Modified-Since`: Automatically added if `Last-Modified` is available
+- `If-None-Match`: Automatically added for revalidation, if an `ETag` is available
+- `If-Modified-Since`: Automatically added for revalidation, if `Last-Modified` is available
 
 **Response headers:**
 - `Cache-Control: max-age`: Used as the expiration time in seconds
+- `Cache-Control: must-revalidate`: When used in combination with `max-age=0`, revalidate immediately.
+- `Cache-Control: no-cache`: Revalidate with the server before using a cached response
 - `Cache-Control: no-store` Skip writing to the cache
 - `Cache-Control: immutable`: Cache the response with no expiration
-- `Expires`: Used as an absolute expiration time
-- `ETag`: Return expired cache data if the remote content has not changed (`304 Not Modified` response)
-- `Last-Modified`: Return expired cache data if the remote content has not changed (`304 Not Modified` response)
+- `Expires`: Used as an absolute expiration datetime
+- `ETag`: Used for revalidation; update and return stale cache data if the remote content has not changed (`304 Not Modified` response)
+- `Last-Modified`: Used for revalidation; update and return stale cache data if the remote content has not changed (`304 Not Modified` response)