Update serialization docs

4 files changed, 27 insertions, 20 deletions

diff --git a/requests_cache/serializers/__init__.py b/requests_cache/serializers/__init__.py
index a1fc1e5..6328ea7 100644
--- a/requests_cache/serializers/__init__.py
+++ b/requests_cache/serializers/__init__.py
@@ -1,4 +1,22 @@
 """Response serialization utilities. See :ref:`serializers` for general usage info.
+
+**Summary:**
+
+The ``cattrs`` library includes a number of `pre-configured converters
+<https://cattrs.readthedocs.io/en/latest/preconf.html>`_ that perform some pre-serialization steps
+required for specific serialization formats.
+
+The module :py:mod:`requests_cache.serializers.preconf` wraps those converters as serializer
+:py:class:`.Stage` objects, which are then combined into a :py:class:`.SerializerPipeline`. Preconf
+converters run after the base converter and before the format's ``dumps()`` (or equivalent) method.
+For example, for JSON:
+
+* Run base converter (:py:class:`.CattrStage`) to convert :py:class:`.CachedResponse` to a dict
+* Run json prconf converter to convert binary response body to base84
+* Run ``json.dumps()``
+
+For any optional libraries that aren't installed, the corresponding serializer will be a placeholder
+class that raises an ``ImportError`` at initialization time instead of at import time.
 """
 # flake8: noqa: F401
 from typing import Union
diff --git a/requests_cache/serializers/cattrs.py b/requests_cache/serializers/cattrs.py
index 3de7079..708975b 100644
--- a/requests_cache/serializers/cattrs.py
+++ b/requests_cache/serializers/cattrs.py
@@ -1,7 +1,7 @@
 """
 Utilities to break down :py:class:`.CachedResponse` objects into a dict of python builtin types
-using `cattrs <https://cattrs.readthedocs.io>`_. This does the majority of the work needed for any
-serialization format.
+using `cattrs <https://cattrs.readthedocs.io>`_. This does the majority of the work needed for all
+serialization formats.
 
 .. automodsumm:: requests_cache.serializers.cattrs
    :classes-only:
diff --git a/requests_cache/serializers/pipeline.py b/requests_cache/serializers/pipeline.py
index 3518229..8f4a521 100644
--- a/requests_cache/serializers/pipeline.py
+++ b/requests_cache/serializers/pipeline.py
@@ -1,4 +1,5 @@
-"""
+"""Classes for building complex serializers from a sequence of stages.
+
 .. automodsumm:: requests_cache.serializers.pipeline
    :classes-only:
    :nosignatures:
diff --git a/requests_cache/serializers/preconf.py b/requests_cache/serializers/preconf.py
index dc871a2..d530ae6 100644
--- a/requests_cache/serializers/preconf.py
+++ b/requests_cache/serializers/preconf.py
@@ -1,26 +1,13 @@
 # flake8: noqa: F841
-"""The ``cattrs`` library includes a number of `pre-configured converters
-<https://cattrs.readthedocs.io/en/latest/preconf.html>`_ that perform some pre-serialization steps
-required for specific serialization formats.
-
-This module wraps those converters as serializer :py:class:`.Stage` objects. These are then used as
-stages in a :py:class:`.SerializerPipeline`, which runs after the base converter and before the
-format's ``dumps()`` (or equivalent) method.
-
-For any optional libraries that aren't installed, the corresponding serializer will be a placeholder
-class that raises an ``ImportError`` at initialization time instead of at import time.
+"""Stages and serializers for supported serialization formats.
 
 .. automodsumm:: requests_cache.serializers.preconf
    :nosignatures:
 """
 import pickle
-from datetime import timedelta
-from decimal import Decimal
 from functools import partial
 from importlib import import_module
 
-from cattr import GenConverter
-
 from .._utils import get_placeholder_class
 from .cattrs import CattrStage, make_decimal_timedelta_converter
 from .pipeline import SerializerPipeline, Stage
@@ -89,7 +76,7 @@ except ImportError as e:
     safe_pickle_serializer = get_placeholder_class(e)
 
 
-# BSON serializer
+# BSON/MongoDB document serializers
 def _get_bson_functions():
     """Handle different function names between pymongo's bson and standalone bson"""
     try:
@@ -150,11 +137,12 @@ except ImportError as e:
     yaml_serializer = get_placeholder_class(e)
 
 
+# DynamoDB document serializer
 dynamodb_preconf_stage = CattrStage(
     factory=make_decimal_timedelta_converter, convert_timedelta=False
-)
+)  #: Pre-serialization steps for DynamoDB
 dynamodb_document_serializer = SerializerPipeline(
     [dynamodb_preconf_stage],
     name='dynamodb_document',
     is_binary=False,
-)
+)  #: DynamoDB-compatible document serializer