From 96e8d252818fcdec60cc94361f81d1428d1269c9 Mon Sep 17 00:00:00 2001
From: Michael Waskom <mwaskom@nyu.edu>
Date: Sat, 19 Jun 2021 10:49:16 -0400
Subject: [PATCH] Documentation in data module

---
 seaborn/_core/data.py | 43 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 36 insertions(+), 7 deletions(-)

diff --git a/seaborn/_core/data.py b/seaborn/_core/data.py
index 526f198232..6c1cf87217 100644
--- a/seaborn/_core/data.py
+++ b/seaborn/_core/data.py
@@ -1,3 +1,6 @@
+"""
+Components for parsing variable assignments and internally representing plot data.
+"""
 from __future__ import annotations
 
 from collections import abc
@@ -9,8 +12,33 @@
     from seaborn._core.typing import DataSource, VariableSpec
 
 
+# TODO Repetition in the docstrings should be reduced with interpolation tools
+
 class PlotData:
-    """Data table with plot variable schema and mapping to original names."""
+    """
+    Data table with plot variable schema and mapping to original names.
+
+    Contains logic for parsing variable specification arguments and updating
+    the table with layer-specific data and/or mappings.
+
+    Parameters
+    ----------
+    data
+        Input data where variable names map to vector values.
+    variables
+        Keys are names of plot variables (x, y, ...) each value is one of:
+
+        - name of a column (or index level, or dictionary entry) in `data`
+        - vector in any format that can construct a :class:`pandas.DataFrame`
+
+    Attributes
+    ----------
+    frame
+        Data table with column names having defined plot variables.
+    names
+        Dictionary mapping plot variable names to names in source data structure(s).
+
+    """
     frame: DataFrame
     names: dict[str, str | None]
     _source: DataSource
@@ -73,21 +101,22 @@ def _assign_variables(
         variables: dict[str, VariableSpec],
     ) -> tuple[DataFrame, dict[str, str | None]]:
         """
-        Define plot variables given long-form data and/or vector inputs.
+        Assign values for plot variables given long-form data and/or vector inputs.
 
         Parameters
         ----------
         data
             Input data where variable names map to vector values.
         variables
-            Keys are seaborn variables (x, y, hue, ...) and values are vectors
-            in any format that can construct a :class:`pandas.DataFrame` or
-            names of columns or index levels in ``data``.
+            Keys are names of plot variables (x, y, ...) each value is one of:
+
+            - name of a column (or index level, or dictionary entry) in `data`
+            - vector in any format that can construct a :class:`pandas.DataFrame`
 
         Returns
         -------
         frame
-            Dataframe mapping seaborn variables (x, y, hue, ...) to data vectors.
+            Table mapping seaborn variables (x, y, hue, ...) to data vectors.
         names
             Keys are defined seaborn variables; values are names inferred from
             the inputs (or None when no name can be determined).
@@ -179,7 +208,7 @@ def _assign_variables(
         # types automatically, aligning on index in case of pandas objects
         frame = pd.DataFrame(plot_data)
 
-        # Reduce the variables dictionary to fields with valid data
+        # Build the mapping from plot variables to original names (if available)
         names = {
             var: name
             for var, name in var_names.items()