From 67c49ffeb5e8a925b316b2c1f9367da48b29f31c Mon Sep 17 00:00:00 2001
From: Derek Jones <dtj1s@uw.edu>
Date: Fri, 11 Oct 2024 13:46:33 -0700
Subject: [PATCH] Improve documentation.

---
 src/nested_pandas/nestedframe/core.py | 86 +++++----------------------
 1 file changed, 16 insertions(+), 70 deletions(-)

diff --git a/src/nested_pandas/nestedframe/core.py b/src/nested_pandas/nestedframe/core.py
index d936d7c..c991863 100644
--- a/src/nested_pandas/nestedframe/core.py
+++ b/src/nested_pandas/nestedframe/core.py
@@ -32,6 +32,10 @@ def _constructor(self) -> Self:  # type: ignore[name-defined] # noqa: F821
     def _constructor_expanddim(self) -> Self:  # type: ignore[name-defined] # noqa: F821
         return NestedFrame
 
+    # https://pandas.pydata.org/docs/development/extending.html#arithmetic-with-3rd-party-types
+    # The __pandas_priority__ of Series is 3000, so give _SeriesFromNest a
+    # higher priority, so that binary operations involving this class and
+    # Series produce instances of this class, preserving the type and origin.
     __pandas_priority__ = 3500
 
 
@@ -67,6 +71,10 @@ class NestedFrame(pd.DataFrame):
     See https://pandas.pydata.org/docs/development/extending.html#subclassing-pandas-data-structures
     """
 
+    # https://pandas.pydata.org/docs/development/extending.html#arithmetic-with-3rd-party-types
+    # The __pandas_priority__ of DataFrame is 4000, so give NestedFrame a
+    # higher priority, so that binary operations involving this class and
+    # Series produce instances of this class, preserving the type and origin.
     __pandas_priority__ = 4500
 
     @property
@@ -336,7 +344,7 @@ def from_lists(cls, df, base_columns=None, list_columns=None, name="nested"):
     def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
         """
 
-        Evaluate a string describing operations on DataFrame columns.
+        Evaluate a string describing operations on NestedFrame columns.
 
         Operates on columns only, not specific rows or elements.  This allows
         `eval` to run arbitrary code, which can make you vulnerable to code
@@ -353,83 +361,21 @@ def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
             The expression string to evaluate.
         inplace : bool, default False
             If the expression contains an assignment, whether to perform the
-            operation inplace and mutate the existing DataFrame. Otherwise,
-            a new DataFrame is returned.
+            operation inplace and mutate the existing NestedFrame. Otherwise,
+            a new NestedFrame is returned.
         **kwargs
             See the documentation for :func:`eval` for complete details
             on the keyword arguments accepted by
-            :meth:`~pandas.DataFrame.query`.
+            :meth:`~pandas.NestedFrame.eval`.
 
         Returns
         -------
-        ndarray, scalar, pandas object, or None
+        ndarray, scalar, pandas object, nested-pandas object, or None
             The result of the evaluation or None if ``inplace=True``.
 
         See Also
         --------
-        DataFrame.query : Evaluates a boolean expression to query the columns
-            of a frame.
-        DataFrame.assign : Can evaluate an expression or function to create new
-            values for a column.
-        eval : Evaluate a Python expression as a string using various
-            backends.
-
-        Notes
-        -----
-        For more details see the API documentation for :func:`~eval`.
-        For detailed examples see :ref:`enhancing performance with eval
-        <enhancingperf.eval>`.
-
-        Examples
-        --------
-        >>> df = pd.DataFrame({'A': range(1, 6), 'B': range(10, 0, -2)})
-        >>> df
-           A   B
-        0  1  10
-        1  2   8
-        2  3   6
-        3  4   4
-        4  5   2
-        >>> df.eval('A + B')
-        0    11
-        1    10
-        2     9
-        3     8
-        4     7
-        dtype: int64
-
-        Assignment is allowed though by default the original DataFrame is not
-        modified.
-
-        >>> df.eval('C = A + B')
-           A   B   C
-        0  1  10  11
-        1  2   8  10
-        2  3   6   9
-        3  4   4   8
-        4  5   2   7
-        >>> df
-           A   B
-        0  1  10
-        1  2   8
-        2  3   6
-        3  4   4
-        4  5   2
-
-        Multiple columns can be assigned to using multi-line expressions:
-
-        >>> df.eval(
-        ...     '''
-        ... C = A + B
-        ... D = A - B
-        ... '''
-        ... )
-           A   B   C  D
-        0  1  10  11 -9
-        1  2   8  10 -6
-        2  3   6   9 -3
-        3  4   4   8  0
-        4  5   2   7  3
+        https://pandas.pydata.org/docs/reference/api/pandas.eval.html
         """
         nested_resolvers = self._get_nested_column_resolvers()
         kwargs["resolvers"] = tuple(kwargs.get("resolvers", ())) + (nested_resolvers,)
@@ -472,8 +418,8 @@ def query(self, expr: str, *, inplace: bool = False, **kwargs) -> NestedFrame |
 
         Returns
         -------
-        DataFrame
-            DataFrame resulting from the provided query expression.
+        NestedFrame
+            NestedFrame resulting from the provided query expression.
 
         Notes
         -----