From 0751d9d4d0958a2afb206d8b8b07cc5dc7746824 Mon Sep 17 00:00:00 2001
From: Jordan Cook <jordan.cook@pioneer.com>
Date: Tue, 19 Apr 2022 15:12:46 -0500
Subject: Update some user docs

---
 docs/user_guide.md               |  4 ++--
 docs/user_guide/compatibility.md |  2 +-
 docs/user_guide/general.md       |  3 ++-
 docs/user_guide/headers.md       | 32 +++++++++++++++++---------------
 4 files changed, 22 insertions(+), 19 deletions(-)

(limited to 'docs')

diff --git a/docs/user_guide.md b/docs/user_guide.md
index c36c1e3..4a38ea2 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -2,8 +2,8 @@
 # {fa}`book` User Guide
 This section covers the main features of requests-cache.
 
+## The Basics
 ```{toctree}
-:caption: The Basics
 :maxdepth: 2
 
 user_guide/installation
@@ -12,8 +12,8 @@ user_guide/files
 user_guide/troubleshooting
 ```
 
+## Features & Options
 ```{toctree}
-:caption: Features & Options
 :maxdepth: 2
 
 user_guide/backends
diff --git a/docs/user_guide/compatibility.md b/docs/user_guide/compatibility.md
index fcd5304..f50e1b0 100644
--- a/docs/user_guide/compatibility.md
+++ b/docs/user_guide/compatibility.md
@@ -1,5 +1,5 @@
 (compatibility)=
-# {fa}`plus-square` Usage with other requests-based libraries
+# {fa}`puzzle-piece` Compatibility with other libraries
 This library works by patching and/or extending {py:class}`requests.Session`. Many other libraries
 out there do the same thing, making it potentially difficult to combine them.
 
diff --git a/docs/user_guide/general.md b/docs/user_guide/general.md
index 7047f04..4083794 100644
--- a/docs/user_guide/general.md
+++ b/docs/user_guide/general.md
@@ -37,7 +37,8 @@ clear out everything at once with {py:meth}`.BaseCache.clear`:
 (patching)=
 ## Patching
 In some situations, it may not be possible or convenient to manage your own session object. In those
-cases, you can use {py:func}`.install_cache` to add caching to all `requests` functions:
+cases, you can use {py:func}`.install_cache`. This adds fully transparent caching to all `requests`
+functions, without the need to modify any existing code:
 ```python
 >>> import requests
 >>> import requests_cache
diff --git a/docs/user_guide/headers.md b/docs/user_guide/headers.md
index 5d7c696..0ce1ee4 100644
--- a/docs/user_guide/headers.md
+++ b/docs/user_guide/headers.md
@@ -1,15 +1,9 @@
 (headers)=
 # {fa}`file-code` Cache Headers
-Most common request and response headers related to caching are supported, including
-[Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control)
-and [ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag).
-
-```{note}
-requests-cache is not (yet) intended to be strict implementation of HTTP caching according to
-[RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616),
-[RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234), etc. If there is additional behavior you
-would like to see, please create an issue to request it.
-```
+Requests-cache supports most common HTTP caching headers, including
+[ETags](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag),
+[Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control),
+and several extensions.
 
 (conditional-requests)=
 ## Conditional Requests
@@ -22,19 +16,20 @@ requests-cache repo:
 ```python
 >>> # Cache a response that will expire immediately
 >>> url = 'https://api.github.com/repos/reclosedev/requests-cache'
->>> session = CachedSession(expire_after=0.0001)
+>>> session = CachedSession(expire_after=1)
 >>> session.get(url)
->>> time.sleep(0.0001)
+>>> time.sleep(1)
 
 >>> # The cached response will still be used until the remote content actually changes
 >>> response = session.get(url)
->>> print(response.from_cache, response.is_expired)
-True, True
+>>> print(response.from_cache)
+True
 ```
 
 ## Cache-Control
 `Cache-Control` **request** headers will always be used if present. This is mainly useful if you are
-adding requests-cache to an existing application or library that already uses caching request headers.
+adding requests-cache to an existing application or library that already sends requests with cache
+headers.
 
 `Cache-Control` **response** headers are an opt-in feature. If enabled, these will take priority over
 any other `expire_after` values. See {ref}`precedence` for the full order of precedence.
@@ -44,6 +39,13 @@ To enable this behavior, use the `cache_control` option:
 ```
 
 ## Supported Headers
+Requests-cache implements the majority of private cache behaviors specified by the following RFCs,
+with some minor variations:
+* [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616)
+* [RFC 5861](https://datatracker.ietf.org/doc/html/rfc5861)
+* [RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234)
+* [RFC 8246](https://datatracker.ietf.org/doc/html/rfc8246)
+
 The following headers are currently supported:
 
 **Request headers:**
-- 
cgit v1.2.1