Improve/harmonize docstrings

Author: hynek

docs/api.rst

@@ -712,4 +712,5 @@ All setters in ``attrs.setters`` are also available from ``attr.setters`` (it's
          ...
      attrs.exceptions.FrozenAttributeError: ()
 
-   N.B. Please use `attrs.define`'s *frozen* argument (or `attrs.frozen`) to freeze whole classes; it is more efficient.
+   .. tip::
+      Use `attrs.define`'s *frozen* argument (or `attrs.frozen`) to freeze whole classes; it is more efficient.

src/attr/_cmp.py

@@ -26,15 +26,15 @@ def cmp_using(
     The resulting class will have a full set of ordering methods if at least
     one of ``{lt, le, gt, ge}`` and ``eq``  are provided.
 
-    :param typing.Callable | None eq: `Callable` used to evaluate equality of two
+    :param typing.Callable | None eq: Callable used to evaluate equality of two
         objects.
-    :param typing.Callable | None lt: `Callable` used to evaluate whether one
+    :param typing.Callable | None lt: Callable used to evaluate whether one
         object is less than another object.
-    :param typing.Callable | None le: `Callable` used to evaluate whether one
+    :param typing.Callable | None le: Callable used to evaluate whether one
         object is less than or equal to another object.
-    :param typing.Callable | None gt: `Callable` used to evaluate whether one
+    :param typing.Callable | None gt: Callable used to evaluate whether one
         object is greater than another object.
-    :param typing.Callable | None ge: `Callable` used to evaluate whether one
+    :param typing.Callable | None ge: Callable used to evaluate whether one
         object is greater than or equal to another object.
 
     :param bool require_same_type: When `True`, equality and ordering methods

src/attr/_funcs.py

@@ -22,22 +22,21 @@ def asdict(
     Optionally recurse into other *attrs*-decorated classes.
 
     :param inst: Instance of an *attrs*-decorated class.
-    :param bool recurse: Recurse into classes that are also
-        *attrs*-decorated.
-    :param callable filter: A callable whose return code determines whether an
-        attribute or element is included (``True``) or dropped (``False``).  Is
-        called with the `attrs.Attribute` as the first argument and the
-        value as the second argument.
-    :param callable dict_factory: A callable to produce dictionaries from.  For
-        example, to produce ordered dictionaries instead of normal Python
-        dictionaries, pass in ``collections.OrderedDict``.
-    :param bool retain_collection_types: Do not convert to ``list`` when
-        encountering an attribute whose type is ``tuple`` or ``set``.  Only
-        meaningful if ``recurse`` is ``True``.
-    :param Optional[callable] value_serializer: A hook that is called for every
-        attribute or dict key/value.  It receives the current instance, field
-        and value and must return the (updated) value.  The hook is run *after*
-        the optional *filter* has been applied.
+    :param bool recurse: Recurse into classes that are also *attrs*-decorated.
+    :param ~typing.Callable filter: A callable whose return code determines
+        whether an attribute or element is included (`True`) or dropped
+        (`False`).  Is called with the `attrs.Attribute` as the first argument
+        and the value as the second argument.
+    :param ~typing.Callable dict_factory: A callable to produce dictionaries
+        from.  For example, to produce ordered dictionaries instead of normal
+        Python dictionaries, pass in ``collections.OrderedDict``.
+    :param bool retain_collection_types: Do not convert to `list` when
+        encountering an attribute whose type is `tuple` or `set`.  Only
+        meaningful if *recurse* is `True`.
+    :param typing.Callable | None value_serializer: A hook that is called for
+        every attribute or dict key/value.  It receives the current instance,
+        field and value and must return the (updated) value.  The hook is run
+        *after* the optional *filter* has been applied.
 
     :rtype: return type of *dict_factory*
 
@@ -207,18 +206,16 @@ def astuple(
     Optionally recurse into other *attrs*-decorated classes.
 
     :param inst: Instance of an *attrs*-decorated class.
-    :param bool recurse: Recurse into classes that are also
-        *attrs*-decorated.
-    :param callable filter: A callable whose return code determines whether an
-        attribute or element is included (``True``) or dropped (``False``).  Is
-        called with the `attrs.Attribute` as the first argument and the
-        value as the second argument.
-    :param callable tuple_factory: A callable to produce tuples from.  For
-        example, to produce lists instead of tuples.
-    :param bool retain_collection_types: Do not convert to ``list``
-        or ``dict`` when encountering an attribute which type is
-        ``tuple``, ``dict`` or ``set``.  Only meaningful if ``recurse`` is
-        ``True``.
+    :param bool recurse: Recurse into classes that are also *attrs*-decorated.
+    :param ~typing.Callable filter: A callable whose return code determines
+        whether an attribute or element is included (`True`) or dropped
+        (`False`).  Is called with the `attrs.Attribute` as the first argument
+        and the value as the second argument.
+    :param ~typing.Callable tuple_factory: A callable to produce tuples from.
+        For example, to produce lists instead of tuples.
+    :param bool retain_collection_types: Do not convert to `list` or `dict`
+        when encountering an attribute which type is `tuple`, `dict` or `set`.
+        Only meaningful if *recurse* is `True`.
 
     :rtype: return type of *tuple_factory*