Some misc docstring edits

6 files changed, 19 insertions, 22 deletions

diff --git a/requests_cache/cache_control.py b/requests_cache/cache_control.py
index a35220c..52e8fa8 100644
--- a/requests_cache/cache_control.py
+++ b/requests_cache/cache_control.py
@@ -1,4 +1,4 @@
-"""Utilities for determining cache expiration and other cache actions"""
+"""Internal utilities for determining cache expiration and other cache actions"""
 from __future__ import annotations
 
 from datetime import datetime, timedelta, timezone
diff --git a/requests_cache/cache_keys.py b/requests_cache/cache_keys.py
index 709d19e..eb0f29e 100644
--- a/requests_cache/cache_keys.py
+++ b/requests_cache/cache_keys.py
@@ -1,4 +1,6 @@
-# TODO: Ignore If-None-Match and If-Modified-Since headers by default
+"""Internal utilities for generating cache keys based on request details + :py:class:`.BaseCache`
+settings
+"""
 from __future__ import annotations
 
 import json
@@ -63,6 +65,7 @@ def remove_ignored_params(
 def remove_ignored_headers(
     request: AnyRequest, ignored_parameters: Optional[Iterable[str]]
 ) -> CaseInsensitiveDict:
+    """Remove any ignored parameters from reuqest headers"""
     if not ignored_parameters:
         return request.headers
     headers = CaseInsensitiveDict(request.headers.copy())
@@ -78,7 +81,7 @@ def remove_ignored_url_params(request: AnyRequest, ignored_parameters: Optional[
         return url_str
 
     url = urlparse(url_str)
-    query = filter_params(parse_qsl(url.query), ignored_parameters)
+    query = _filter_params(parse_qsl(url.query), ignored_parameters)
     return urlunparse((url.scheme, url.netloc, url.path, url.params, urlencode(query), url.fragment))
 
 
@@ -93,11 +96,11 @@ def remove_ignored_body_params(
         return encode(original_body)
 
     if content_type == 'application/x-www-form-urlencoded':
-        body = filter_params(parse_qsl(decode(original_body)), ignored_parameters)
+        body = _filter_params(parse_qsl(decode(original_body)), ignored_parameters)
         filtered_body = urlencode(body)
     elif content_type == 'application/json':
         body = json.loads(decode(original_body)).items()
-        body = filter_params(sorted(body), ignored_parameters)
+        body = _filter_params(sorted(body), ignored_parameters)
         filtered_body = json.dumps(body)
     else:
         filtered_body = original_body
@@ -105,7 +108,7 @@ def remove_ignored_body_params(
     return encode(filtered_body)
 
 
-def filter_params(
+def _filter_params(
     data: List[Tuple[str, str]], ignored_parameters: Iterable[str]
 ) -> List[Tuple[str, str]]:
     return [(k, v) for k, v in data if k not in set(ignored_parameters)]
@@ -141,6 +144,7 @@ def normalize_dict(
 
 
 def url_to_key(url: str, *args, **kwargs) -> str:
+    """Create a cache key from a request URL"""
     request = Session().prepare_request(Request('GET', url))
     return create_key(request, *args, **kwargs)
 
@@ -152,6 +156,6 @@ def encode(value, encoding='utf-8') -> bytes:
 
 def decode(value, encoding='utf-8') -> str:
     """Decode a value from bytes, if hasn't already been.
-    Note: PreparedRequest.body is always encoded in utf-8.
+    Note: ``PreparedRequest.body`` is always encoded in utf-8.
     """
     return value.decode(encoding) if isinstance(value, bytes) else value
diff --git a/requests_cache/models/raw_response.py b/requests_cache/models/raw_response.py
index 134aa96..8275100 100644
--- a/requests_cache/models/raw_response.py
+++ b/requests_cache/models/raw_response.py
@@ -10,11 +10,11 @@ logger = getLogger(__name__)
 
 @define(auto_attribs=False, slots=False)
 class CachedHTTPResponse(HTTPResponse):
-    """A serializable dataclass that extends/emulates :py:class:`~urllib3.response.HTTPResponse`.
+    """A serializable dataclass that emulates :py:class:`~urllib3.response.HTTPResponse`.
     Supports streaming requests and generator usage.
 
     The only action this doesn't support is explicitly calling :py:meth:`.read` with
-    ``decode_content=False``, but a use case for this has not come up yet.
+    ``decode_content=False``.
     """
 
     decode_content: bool = field(default=None)
diff --git a/requests_cache/models/request.py b/requests_cache/models/request.py
index c72aadb..46951fc 100644
--- a/requests_cache/models/request.py
+++ b/requests_cache/models/request.py
@@ -1,4 +1,3 @@
-"""Classes to wrap cached response objects"""
 from logging import getLogger
 
 from attr import define, field, fields_dict
diff --git a/requests_cache/models/response.py b/requests_cache/models/response.py
index 2fb0ea9..229fd6a 100755
--- a/requests_cache/models/response.py
+++ b/requests_cache/models/response.py
@@ -1,4 +1,3 @@
-"""Classes to wrap cached response objects"""
 from datetime import datetime, timedelta, timezone
 from logging import getLogger
 from typing import TYPE_CHECKING, List, Optional, Tuple, Union
@@ -18,13 +17,8 @@ logger = getLogger(__name__)
 
 @define(auto_attribs=False, slots=False)
 class CachedResponse(Response):
-    """A serializable dataclass that emulates :py:class:`requests.Response`. Public attributes and
-    methods on CachedResponse objects will behave the same as those from the original response, but
-    with different internals optimized for serialization.
-
-    This means doing some pre- and post-initialization steps common to all serializers, such as
-    breaking nested objects down into their basic attributes and lazily re-initializing them, which
-    saves a bit of memory and deserialization steps when those objects aren't accessed.
+    """A class that emulates :py:class:`requests.Response`, with some additional optimizations
+    for serialization.
     """
 
     _content: bytes = field(default=None)
diff --git a/requests_cache/session.py b/requests_cache/session.py
index 3d85bac..798f072 100644
--- a/requests_cache/session.py
+++ b/requests_cache/session.py
@@ -26,7 +26,7 @@ else:
 
 class CacheMixin(MIXIN_BASE):
     """Mixin class that extends :py:class:`requests.Session` with caching features.
-    See :py:class:`.CachedSession` for usage information.
+    See :py:class:`.CachedSession` for usage details.
     """
 
     def __init__(
@@ -268,7 +268,7 @@ class CacheMixin(MIXIN_BASE):
 
 
 class CachedSession(CacheMixin, OriginalSession):
-    """Class that extends :py:class:`requests.Session` with caching features.
+    """Session class that extends :py:class:`requests.Session` with caching features.
 
     See individual :py:mod:`backend classes <requests_cache.backends>` for additional backend-specific arguments.
     Also see :ref:`user-guide` for more details and examples on how the following arguments
@@ -295,8 +295,8 @@ class CachedSession(CacheMixin, OriginalSession):
 
 @contextmanager
 def patch_form_boundary(**request_kwargs):
-    """This patches the form boundary used to separate multipart uploads. Requests does not
-    provide a way to pass a custom boundary to urllib3, so this just monkey-patches it instead.
+    """Patch the form boundary used to separate multipart uploads. ``requests`` does not provide a
+    way to pass a custom boundary to urllib3, so this just monkey-patches it instead.
     """
     if request_kwargs.get('files'):
         original_boundary = filepost.choose_boundary