Some more documentation updates & editing

2 files changed, 35 insertions, 13 deletions

diff --git a/docs/advanced_usage.rst b/docs/advanced_usage.rst
index ded4129..047d9e8 100644
--- a/docs/advanced_usage.rst
+++ b/docs/advanced_usage.rst
@@ -71,25 +71,47 @@ responses they redirect to.
 
 Custom Backends
 ---------------
-If the built-in :py:mod:`Cache Backends <requests_cache.backends>` don't suit your needs, you can create your own by
-making subclasses of :py:class:`.BaseCache` and :py:class:`.BaseStorage`:
+If the built-in :py:mod:`Cache Backends <requests_cache.backends>` don't suit your needs, you can
+create your own by making subclasses of :py:class:`.BaseCache` and :py:class:`.BaseStorage`:
 
     >>> from requests_cache import CachedSession
     >>> from requests_cache.backends import BaseCache, BaseStorage
     >>>
-    >>> class MyCache(BaseCache):
-    >>>     """Wrapper for higher-level cache operations"""
-    >>>     def __init__(self, **kwargs):
-    >>>         super().__init__(**kwargs)
-    >>>         self.redirects = MyStorage(**kwargs)
-    >>>         self.responses = MyStorage(**kwargs)
+    >>> class CustomCache(BaseCache):
+    ...     """Wrapper for higher-level cache operations. In most cases, the only thing you need
+    ...     to specify here is which storage class(es) to use.
+    ...     """
+    ...     def __init__(self, **kwargs):
+    ...         super().__init__(**kwargs)
+    ...         self.redirects = CustomStorage(**kwargs)
+    ...         self.responses = CustomStorage(**kwargs)
     >>>
-    >>> class MyStorage(BaseStorage):
-    >>>     """Lower-level backend storage operations"""
+    >>> class CustomStorage(BaseStorage):
+    ...     """Dict-like interface for lower-level backend storage operations"""
+    ...     def __init__(self, **kwargs):
+    ...         super().__init__(**kwargs)
+    ...
+    ...     def __getitem__(self, key):
+    ...         pass
+    ...
+    ...     def __setitem__(self, key, value):
+    ...         pass
+    ...
+    ...     def __delitem__(self, key):
+    ...         pass
+    ...
+    ...     def __iter__(self):
+    ...         pass
+    ...
+    ...     def __len__(self):
+    ...         pass
+    ...
+    ...     def clear(self):
+    ...         pass
 
 You can then use your custom backend in a :py:class:`.CachedSession` with the ``backend`` parameter:
 
-    >>> session = CachedSession(backend=MyCache())
+    >>> session = CachedSession(backend=CustomCache())
 
 Usage with other requests features
 ----------------------------------
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 3610f9e..add049a 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -12,7 +12,7 @@ Requirements
 ~~~~~~~~~~~~
 * Requires python 3.6+.
 * You may need additional dependencies depending on which backend you want to use. To install with
-  extra dependencies for all supported backends:
+  extra dependencies for all supported :ref:`user_guide:cache backends`:
 
     $ pip install requests-cache[backends]
 
@@ -51,7 +51,7 @@ Caching can be temporarily disabled with :py:meth:`.CachedSession.cache_disabled
     ...     session.get('http://httpbin.org/get')
 
 The best way to clean up your cache is through :ref:`user_guide:cache expiration`, but you can also
-clear out everything with :py:meth:`.BaseCache.clear`:
+clear out everything at once with :py:meth:`.BaseCache.clear`:
 
     >>> session.cache.clear()