docstring tweaks for first

boltons/iterutils.py

@@ -415,29 +415,27 @@ def one(src, cmp=None):
 
 
 def first(iterable, default=None, key=None):
-    """Return first element of `iterable` that evaluates true, else return None
-    (or an optional default value).
+    """Return first element of *iterable* that evaluates to ``True``, else
+    return ``None`` or optional *default*.
 
     >>> first([0, False, None, [], (), 42])
     42
-
     >>> first([0, False, None, [], ()]) is None
     True
-
     >>> first([0, False, None, [], ()], default='ohai')
     'ohai'
-
     >>> import re
     >>> m = first(re.match(regex, 'abc') for regex in ['b.*', 'a(.*)'])
     >>> m.group(1)
     'bc'
 
-    The optional `key` argument specifies a one-argument predicate function
-    like that used for `filter()`.  The `key` argument, if supplied, must be
-    in keyword form.  For example:
+    The optional *key* argument specifies a one-argument predicate function
+    like that used for *filter()*.  The *key* argument, if supplied, should be
+    in keyword form. For example, finding the first even number in an iterable:
 
     >>> first([1, 1, 3, 4, 5], key=lambda x: x % 2 == 0)
     4
+
     """
     if key is None:
         for el in iterable: