Add narrative docs for #787 (#801)

changelog.d/787.change.rst

@@ -1 +1,3 @@
-To make it easier to customize attribute comparison (#435), add the ``attr.cmp_with()`` helper.
+To make it easier to customize attribute comparison (#435), we have added the ``attr.cmp_with()`` helper.
+
+See the `new docs on comparison <https://www.attrs.org/en/stable/comparison.html>`_ for more details.

docs/api.rst

@@ -173,6 +173,8 @@ Helpers
 
 ``attrs`` comes with a bunch of helper methods that make working with it easier:
 
+.. autofunction:: attr.cmp_using
+
 .. autofunction:: attr.fields
 
    For example:

docs/comparison.rst

@@ -42,5 +42,17 @@ It is then used as a key function like you may know from `sorted`:
 This is especially useful when you have fields with objects that have atypical comparison properties.
 Common examples of such objects are `NumPy arrays <https://github.com/python-attrs/attrs/issues/435>`_.
 
-Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs <next-gen>`.
-You can set both at once by using the *cmp* argument that we've undeprecated just for this use-case.
+To save you unnecessary boilerplate, ``attrs`` comes with the `attr.cmp_using` helper to create such functions.
+For NumPy arrays it would look like this::
+
+   import numpy as np
+
+   @attr.s(order=False)
+   class C:
+      an_array = attr.ib(eq=attr.cmp_using(eq=np.array_equal))
+
+
+.. warning::
+
+   Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs <next-gen>`.
+   You can set both at once by using the *cmp* argument that we've undeprecated just for this use-case.

src/attr/_cmp.py

@@ -19,8 +19,8 @@ def cmp_using(
     class_name="Comparable",
 ):
     """
-    Utility function that creates a class with customized equality and
-    ordering methods.
+    Create a class that can be passed into `attr.ib`'s ``eq``, ``order``, and
+    ``cmp`` arguments to customize field comparison.
 
     The resulting class will have a full set of ordering methods if
     at least one of ``{lt, le, gt, ge}`` and ``eq``  are provided.
@@ -41,6 +41,8 @@ def cmp_using(
 
     :param Optional[str] class_name: Name of class. Defaults to 'Comparable'.
 
+    See `comparison` for more details.
+
     .. versionadded:: 21.1.0
     """