Tune multidict docs (#1205)

1. Put `extend()` and `update()` docs in the same logical group to
display bulk update methods together
2. Mention `kwargs` as accepted argument for both `extend()` and
`update()`.

Author: asvetlov

CHANGES/1205.doc.rst

@@ -0,0 +1 @@
+Improved documentation for :meth:`multidict.MultiDict.extend` and :meth:`multidict.MultiDict.update` -- by :user:`asvetlov`.

docs/multidict.rst

@@ -71,23 +71,6 @@ MultiDict
 
       Return a shallow copy of the dictionary.
 
-   .. method:: extend([other])
-
-      Extend the dictionary with the key/value pairs from *other*,
-      appending the pairs to this dictionary. For existing keys,
-      values are added.
-      Returns ``None``.
-
-      :meth:`extend` accepts either another dictionary object or an
-      iterable of key/value pairs (as tuples or other iterables of
-      length two). If keyword arguments are specified, the dictionary
-      is then extended with those key/value pairs:
-      ``d.extend(red=1, blue=2)``.
-
-      Effectively the same as calling :meth:`add` for every
-      ``(key, value)`` pair. Also see :meth:`update`, for a version
-      that replaces existing keys.
-
    .. method:: getone(key[, default])
 
       Return the **first** value for *key* if *key* is in the
@@ -179,9 +162,30 @@ MultiDict
       If not, insert *key* with a value of *default* and return *default*.
       *default* defaults to ``None``.
 
-   .. method:: update([other])
+   .. method:: extend([other], **kwargs)
+
+      Extend the dictionary with the key/value pairs from *other* and *kwargs*,
+      appending the pairs to this dictionary. For existing keys,
+      values are added.
 
-      Update the dictionary with the key/value pairs from *other*,
+      Returns ``None``.
+
+      :meth:`extend` accepts either another dictionary object or an
+      iterable of key/value pairs (as tuples or other iterables of
+      length two). If keyword arguments are specified, the dictionary
+      is then extended with those key/value pairs:
+      ``d.extend(red=1, blue=2)``.
+
+      Effectively the same as calling :meth:`add` for every
+      ``(key, value)`` pair.
+
+      .. seealso::
+
+         :meth:`update`
+
+   .. method:: update([other], **kwargs)
+
+      Update the dictionary with the key/value pairs from *other* and *kwargs*,
       overwriting existing keys.
 
       Returns ``None``.
@@ -192,8 +196,9 @@ MultiDict
       dictionary is then updated with those key/value pairs:
       ``d.update(red=1, blue=2)``.
 
-      Also see :meth:`extend` for a method that adds to existing keys rather
-      than update them.
+      .. seealso::
+
+         :meth:`extend`
 
    .. seealso::
 
@@ -444,7 +449,7 @@ Environment variables
       its C counterpart, depending on the way it's used.
 
 .. envvar:: MULTIDICT_DEBUG_BUILD
-   
+
    An environment variable that instructs the packaging scripts to compile
    the C-extension based variant of :mod:`multidict` with debug symbols.
    This is useful for debugging the C-extension code, but it will result in