Document comparison (#768)

* Document comparison

* Grammar

* Stress independence of eq/order

* Add example for eq

* Be consistent with fields

* Update docs/comparison.rst

Co-authored-by: Julian Berman <Julian@GrayVines.com>

* Update docs/comparison.rst

Co-authored-by: Julian Berman <Julian@GrayVines.com>

* Update docs/comparison.rst

Co-authored-by: Julian Berman <Julian@GrayVines.com>

* Clarify

Co-authored-by: Julian Berman <Julian@GrayVines.com>

docs/comparison.rst

@@ -0,0 +1,45 @@
+Comparison
+==========
+
+By default, two instances of ``attrs`` classes are equal if all their fields are equal.
+For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you.
+
+Additionally, if you pass ``order=True`` (which is the default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined fields: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``.
+
+
+Customization
+-------------
+
+As with other features, you can exclude fields from being involved in comparison operations:
+
+.. doctest::
+
+   >>> import attr
+   >>> @attr.s
+   ... class C(object):
+   ...     x = attr.ib()
+   ...     y = attr.ib(eq=False)
+   >>> C(1, 2) == C(1, 3)
+   True
+
+Additionally you can also pass a *callable* instead of a bool to both *eq* and *order*.
+It is then used as a key function like you may know from `sorted`:
+
+.. doctest::
+
+   >>> import attr
+   >>> @attr.s
+   ... class S(object):
+   ...     x = attr.ib(eq=str.lower)
+   >>> S("foo") == S("FOO")
+   True
+   >>> @attr.s
+   ... class C(object):
+   ...     x = attr.ib(order=int)
+   >>> C("10") > C("2")
+   True
+
+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 <prov>`.

docs/index.rst

@@ -41,6 +41,8 @@ Day-to-Day Usage
 - Instance initialization is one of ``attrs`` key feature areas.
   Our goal is to relieve you from writing as much code as possible.
   `init` gives you an overview what ``attrs`` has to offer and explains some related philosophies we believe in.
+- Comparing and ordering objects is a common task.
+  `comparison` shows you how ``attrs`` helps you with that and how you can customize it.
 - If you want to put objects into sets or use them as keys in dictionaries, they have to be hashable.
   The simplest way to do that is to use frozen classes, but the topic is more complex than it seems and `hashing` will give you a primer on what to look out for.
 - Once you're comfortable with the concepts, our `api` contains all information you need to use ``attrs`` to its fullest.
@@ -67,6 +69,7 @@ Full Table of Contents
    examples
    types
    init
+   comparison
    hashing
    api
    extending