Add docstrings for composite objects--although these

classes are going to be replaced by a new ProxyGroup
almost immediately.

datatest/_query/query.py

@@ -1489,8 +1489,8 @@ def __init__(self, *args, **kwds):
 
 
 class CompositeQuery(Sequence):
-    """A class to wrap multiple Query instances so they can be
-    worked with like a single Query.
+    """A class to wrap multiple :class:`Query` instances so they can
+    be worked with like a single Query.
     """
     def __init__(self, *queries):
         for argnum, query in enumerate(queries, 1):
@@ -1572,8 +1572,39 @@ def fetch(self):
 
 
 class CompositeSelector(Sequence):
-    """A class to wrap multiple Selector instances so they can be
-    worked with like a single Selector.
+    """A class to wrap multiple :class:`Selector` instances so they
+    can be worked with like a single Selector. The CompositeSelector
+    can be treated as a sequence that can be unpacked into individual
+    objects for validation:
+
+    .. code-block:: python
+        :emphasize-lines: 8
+
+        ...
+
+        compare = CompositeSelector(
+            Selector('detailed_file.csv'),
+            Selector('reference_file.csv'),
+        )
+
+        validate(*compare({'state'}))
+
+    In the example above, we selected the set of values in the "state"
+    column from each file (using ``{'state'}``) and passed the two
+    return values to :func:`validate` using *argument unpacking* (with
+    ``*``).
+
+    This is a shorthand for:
+
+    .. code-block:: python
+        :emphasize-lines: 6
+
+        ...
+
+        detailed = Select('detailed_file.csv')
+        reference = Select('reference_file.csv')
+
+        validate(detailed({'state'}), reference({'state'}))
     """
     def __init__(self, *selectors):
         for argnum, select in enumerate(selectors, 1):

docs/reference/data-handling.rst

@@ -119,3 +119,29 @@ Selecting & Querying Data
 
         The underlying iterator---useful when introspecting
         or rewrapping.
+
+
+*****************
+Composite Objects
+*****************
+
+.. autoclass:: CompositeSelector
+
+.. autoclass:: CompositeQuery
+
+
+Working With Composite Objects
+==============================
+
+Composite objects are useful when you need to compare data from
+multiple sources that are similarly shaped (i.e., they have many
+of the same column names). Rather than select the same columns
+and build the same queries for each data source, you can wrap
+them in a composite object and build the query once::
+
+    select1 = Selector('detailed_data.csv')
+    select2 = Selector('summary_reference.csv')
+    compare = CompositeSelector(select1, select2)
+
+    comparison = compare({'county': 'population'}).sum()
+