Add information about MultiDict to the multidict API docs

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/api/multidict.txt b/docs/api/multidict.txt
index 77f158b..1271b3d 100644
--- a/docs/api/multidict.txt
+++ b/docs/api/multidict.txt
@@ -1,6 +1,28 @@
 :mod:`webob.multidict` -- multi-value dictionary object
 =======================================================
 
+multidict
+---------
+
+Several parts of WebOb use a "multidict", which is a dictionary where a key can
+have multiple values. The quintessential example is a query string like
+``?pref=red&pref=blue``. The ``pref`` variable has two values, ``red`` and
+``blue``.
+
+In a multidict, when you do ``request.GET['pref']``, you'll get back only
+``'blue'`` (the last value of ``pref``).  Sometimes returning a string and
+other times returning a list is a cause of frequent exceptions.  If you want
+*all* the values back, use ``request.GET.getall('pref')``. If you want to be
+sure there is *one and only one* value, use ``request.GET.getone('pref')``,
+which will raise an exception if there is zero or more than one value for
+``pref``.
+
+When you use operations like ``request.GET.items()``, you'll get back something
+like ``[('pref', 'red'), ('pref', 'blue')]``. All the key/value pairs will
+show up.  Similarly ``request.GET.keys()`` returns ``['pref', 'pref']``.
+Multidict is a view on a list of tuples; all the keys are ordered, and all the
+values are ordered.
+
 .. automodule:: webob.multidict
 .. autoclass:: MultiDict
    :members: