- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as

  interface API documentation.

4 files changed, 46 insertions, 30 deletions

diff --git a/docs/api/interfaces.rst b/docs/api/interfaces.rst
index 54afdc830..ac282fbcc 100644
--- a/docs/api/interfaces.rst
+++ b/docs/api/interfaces.rst
@@ -54,3 +54,7 @@ Other Interfaces
   .. autointerface:: IViewMapper
      :members:
 
+  .. autointerface:: IMultiDict
+     :members:
+
+
diff --git a/docs/api/request.rst b/docs/api/request.rst
index 639d0fcd8..8cb424658 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -177,3 +177,9 @@
       (such as the status code, a header, the content type, etc) see,
       :ref:`response_prefixed_attrs`.
 
+.. note::
+
+   For information about the API of a :term:`multidict` structure (such as
+   that used as ``request.GET``, ``request.POST``, and ``request.params``),
+   see :class:`pyramid.interfaces.IMultiDict`.
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 97fc68707..13de8c41a 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -630,10 +630,10 @@ Glossary
       more information.
 
    multidict
-     An ordered dictionary that can have multiple values for each
-     key. Adds the methods ``getall``, ``getone``, ``mixed``, and
-     ``add`` to the normal dictionary interface.  See
-     http://pythonpaste.org/webob/class-webob.multidict.MultiDict.html
+     An ordered dictionary that can have multiple values for each key. Adds
+     the methods ``getall``, ``getone``, ``mixed``, ``add`` and
+     ``dict_of_lists`` to the normal dictionary interface.  See
+     :ref:`multidict_narr` and :class:`pyramid.interfaces.IMultiDict`.
 
    PyPI
      `The Python Package Index <http://pypi.python.org/pypi>`_, a
diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst
index 26a40a59b..072ca1c74 100644
--- a/docs/narr/webob.rst
+++ b/docs/narr/webob.rst
@@ -208,6 +208,38 @@ If it is set, then ``req.POST``, ``req.GET``, ``req.params``, and
 corresponding ``req.str_*`` (e.g., ``req.str_POST``) that is always
 a ``str``, and never unicode.
 
+.. index::
+   single: multidict (WebOb)
+
+.. _multidict_narr:
+
+Multidict
++++++++++
+
+Several attributes of a WebOb request are "multidict"; structures (such as
+``request.GET``, ``request.POST``, and ``request.params``).  A multidict 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 sometimes returning a list, is the 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.
+
+API documentation for a multidict exists as
+:class:`pyramid.interfaces.IMultiDict`.
+
 More Details
 ++++++++++++
 
@@ -371,9 +403,6 @@ The exceptions are still WSGI applications, but you cannot set
 attributes like ``content_type``, ``charset``, etc. on these exception
 objects.
 
-.. index::
-   single: multidict (WebOb)
-
 More Details
 ++++++++++++
 
@@ -382,26 +411,3 @@ More details about the response object API are available in the
 are in the :mod:`pyramid.httpexceptions` API documentation.  The `WebOb
 documentation <http://pythonpaste.org/webob>`_ is also useful.
 
-Multidict
-~~~~~~~~~
-
-Several parts of WebOb use a "multidict"; this 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 sometimes returning a list, is the 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.
-