Added links and cosmetic edits to docs/ref/request-response.txt.

docs/ref/request-response.txt

@@ -40,9 +40,10 @@ All attributes should be considered read-only, unless stated otherwise.
 
     The raw HTTP request body as a byte string. This is useful for processing
     data in different ways than conventional HTML forms: binary images,
-    XML payload etc. For processing conventional form data, use ``HttpRequest.POST``.
+    XML payload etc. For processing conventional form data, use
+    :attr:`HttpRequest.POST`.
 
-    You can also read from an HttpRequest using a file-like interface. See
+    You can also read from an ``HttpRequest`` using a file-like interface. See
     :meth:`HttpRequest.read()`.
 
 .. attribute:: HttpRequest.path
@@ -68,7 +69,7 @@ All attributes should be considered read-only, unless stated otherwise.
 .. attribute:: HttpRequest.method
 
     A string representing the HTTP method used in the request. This is
-    guaranteed to be uppercase. Example::
+    guaranteed to be uppercase. For example::
 
         if request.method == 'GET':
             do_something()
@@ -81,8 +82,9 @@ All attributes should be considered read-only, unless stated otherwise.
     data (or ``None``, which means the :setting:`DEFAULT_CHARSET` setting is
     used). You can write to this attribute to change the encoding used when
     accessing the form data. Any subsequent attribute accesses (such as reading
-    from ``GET`` or ``POST``) will use the new ``encoding`` value.  Useful if
+    from :attr:`GET` or :attr:`POST`) will use the new ``encoding`` value.
-    you know the form data is not in the :setting:`DEFAULT_CHARSET` encoding.
+    Useful if you know the form data is not in the :setting:`DEFAULT_CHARSET`
+    encoding.
 
 .. attribute:: HttpRequest.content_type
 
@@ -111,14 +113,13 @@ All attributes should be considered read-only, unless stated otherwise.
     dictionary -- if, say, a form is requested via the POST HTTP method but
     does not include form data. Therefore, you shouldn't use ``if request.POST``
     to check for use of the POST method; instead, use ``if request.method ==
-    "POST"`` (see above).
+    "POST"`` (see :attr:`HttpRequest.method`).
 
-    Note: ``POST`` does *not* include file-upload information. See ``FILES``.
+    ``POST`` does *not* include file-upload information. See :attr:`FILES`.
 
 .. attribute:: HttpRequest.COOKIES
 
-    A standard Python dictionary containing all cookies. Keys and values are
+    A dictionary containing all cookies. Keys and values are strings.
-    strings.
 
 .. attribute:: HttpRequest.FILES
 
@@ -128,16 +129,14 @@ All attributes should be considered read-only, unless stated otherwise.
 
     See :doc:`/topics/files` for more information.
 
-    Note that ``FILES`` will only contain data if the request method was POST
+    ``FILES`` will only contain data if the request method was POST and the
-    and the ``<form>`` that posted to the request had
+    ``<form>`` that posted to the request had ``enctype="multipart/form-data"``.
-    ``enctype="multipart/form-data"``. Otherwise, ``FILES`` will be a blank
+    Otherwise, ``FILES`` will be a blank dictionary-like object.
-    dictionary-like object.
 
 .. attribute:: HttpRequest.META
 
-    A standard Python dictionary containing all available HTTP headers.
+    A dictionary containing all available HTTP headers. Available headers
-    Available headers depend on the client and server, but here are some
+    depend on the client and server, but here are some examples:
-    examples:
 
     * ``CONTENT_LENGTH`` -- The length of the request body (as a string).
     * ``CONTENT_TYPE`` -- The MIME type of the request body.
@@ -349,7 +348,7 @@ Methods
     Returns ``True`` if the request was made via an ``XMLHttpRequest``, by
     checking the ``HTTP_X_REQUESTED_WITH`` header for the string
     ``'XMLHttpRequest'``. Most modern JavaScript libraries send this header.
-    If you write your own XMLHttpRequest call (on the browser side), you'll
+    If you write your own ``XMLHttpRequest`` call (on the browser side), you'll
     have to set this header manually if you want ``is_ajax()`` to work.
 
     If a response varies on whether or not it's requested via AJAX and you are
@@ -365,13 +364,14 @@ Methods
 .. method:: HttpRequest.__iter__()
 
     Methods implementing a file-like interface for reading from an
-    HttpRequest instance. This makes it possible to consume an incoming
+    ``HttpRequest`` instance. This makes it possible to consume an incoming
     request in a streaming fashion. A common use-case would be to process a
     big XML payload with an iterative parser without constructing a whole
     XML tree in memory.
 
-    Given this standard interface, an HttpRequest instance can be
+    Given this standard interface, an ``HttpRequest`` instance can be
-    passed directly to an XML parser such as ElementTree::
+    passed directly to an XML parser such as
+    :class:`~xml.etree.ElementTree.ElementTree`::
 
         import xml.etree.ElementTree as ET
         for element in ET.iterparse(request):
@@ -383,15 +383,15 @@ Methods
 
 .. class:: QueryDict
 
-In an :class:`HttpRequest` object, the ``GET`` and ``POST`` attributes are
+In an :class:`HttpRequest` object, the :attr:`~HttpRequest.GET` and
-instances of ``django.http.QueryDict``, a dictionary-like class customized to
+`attr:`~HttpRequest.POST` attributes are instances of ``django.http.QueryDict``,
-deal with multiple values for the same key. This is necessary because some HTML
+a dictionary-like class customized to deal with multiple values for the same
-form elements, notably ``<select multiple>``, pass multiple values for the same
+key. This is necessary because some HTML form elements, notably
-key.
+``<select multiple>``, pass multiple values for the same key.
 
 The ``QueryDict``\ s at ``request.POST`` and ``request.GET`` will be immutable
 when accessed in a normal request/response cycle. To get a mutable version you
-need to use ``.copy()``.
+need to use :meth:`QueryDict.copy`.
 
 Methods
 -------
@@ -415,7 +415,8 @@ a subclass of dictionary. Exceptions are outlined here:
     ``mutable=True`` to its ``__init__()``.
 
     Strings for setting both keys and values will be converted from ``encoding``
-    to ``str``. If encoding is not set, it defaults to :setting:`DEFAULT_CHARSET`.
+    to ``str``. If ``encoding`` is not set, it defaults to
+    :setting:`DEFAULT_CHARSET`.
 
 .. classmethod:: QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)
 
@@ -430,17 +431,17 @@ a subclass of dictionary. Exceptions are outlined here:
 .. method:: QueryDict.__getitem__(key)
 
     Returns the value for the given key. If the key has more than one value,
-    ``__getitem__()`` returns the last value. Raises
+    it returns the last value. Raises
     ``django.utils.datastructures.MultiValueDictKeyError`` if the key does not
-    exist. (This is a subclass of Python's standard ``KeyError``, so you can
+    exist. (This is a subclass of Python's standard :exc:`KeyError`, so you can
     stick to catching ``KeyError``.)
 
 .. method:: QueryDict.__setitem__(key, value)
 
-    Sets the given key to ``[value]`` (a Python list whose single element is
+    Sets the given key to ``[value]`` (a list whose single element is
     ``value``). Note that this, as other dictionary functions that have side
     effects, can only be called on a mutable ``QueryDict`` (such as one that
-    was created via ``copy()``).
+    was created via :meth:`QueryDict.copy`).
 
 .. method:: QueryDict.__contains__(key)
 
@@ -449,19 +450,18 @@ a subclass of dictionary. Exceptions are outlined here:
 
 .. method:: QueryDict.get(key, default=None)
 
-    Uses the same logic as ``__getitem__()`` above, with a hook for returning a
+    Uses the same logic as :meth:`__getitem__`, with a hook for returning a
     default value if the key doesn't exist.
 
 .. method:: QueryDict.setdefault(key, default=None)
 
-    Just like the standard dictionary ``setdefault()`` method, except it uses
+    Like :meth:`dict.setdefault`, except it uses :meth:`__setitem__` internally.
-    ``__setitem__()`` internally.
 
 .. method:: QueryDict.update(other_dict)
 
-    Takes either a ``QueryDict`` or standard dictionary. Just like the standard
+    Takes either a ``QueryDict`` or a dictionary. Like :meth:`dict.update`,
-    dictionary ``update()`` method, except it *appends* to the current
+    except it *appends* to the current dictionary items rather than replacing
-    dictionary items rather than replacing them. For example::
+    them. For example::
 
         >>> q = QueryDict('a=1', mutable=True)
         >>> q.update({'a': '2'})
@@ -472,8 +472,8 @@ a subclass of dictionary. Exceptions are outlined here:
 
 .. method:: QueryDict.items()
 
-    Just like the standard dictionary ``items()`` method, except this uses the
+    Like :meth:`dict.items`, except this uses the same last-value logic as
-    same last-value logic as ``__getitem__()``. For example::
+    :meth:`__getitem__`. For example::
 
         >>> q = QueryDict('a=1&a=2&a=3')
         >>> q.items()
@@ -481,8 +481,8 @@ a subclass of dictionary. Exceptions are outlined here:
 
 .. method:: QueryDict.values()
 
-    Just like the standard dictionary ``values()`` method, except this uses the
+    Like :meth:`dict.values`, except this uses the same last-value logic as
-    same last-value logic as ``__getitem__()``. For example::
+    :meth:`__getitem__`. For example::
 
         >>> q = QueryDict('a=1&a=2&a=3')
         >>> q.values()
@@ -492,19 +492,18 @@ In addition, ``QueryDict`` has the following methods:
 
 .. method:: QueryDict.copy()
 
-    Returns a copy of the object, using ``copy.deepcopy()`` from the Python
+    Returns a copy of the object using :func:`copy.deepcopy`. This copy will
-    standard library. This copy will be mutable even if the original was not.
+    be mutable even if the original was not.
 
 .. method:: QueryDict.getlist(key, default=None)
 
-    Returns the data with the requested key, as a Python list. Returns an
+    Returns a list of the data with the requested key. Returns an empty list if
-    empty list if the key doesn't exist and no default value was provided.
+    the key doesn't exist and a default value wasn't provided. It's guaranteed
-    It's guaranteed to return a list of some sort unless the default value
+    to return a list unless the default value provided isn't a list.
-    provided is not a list.
 
 .. method:: QueryDict.setlist(key, list_)
 
-    Sets the given key to ``list_`` (unlike ``__setitem__()``).
+    Sets the given key to ``list_`` (unlike :meth:`__setitem__`).
 
 .. method:: QueryDict.appendlist(key, item)
 
@@ -512,7 +511,7 @@ In addition, ``QueryDict`` has the following methods:
 
 .. method:: QueryDict.setlistdefault(key, default_list=None)
 
-    Just like ``setdefault``, except it takes a list of values instead of a
+    Like :meth:`setdefault`, except it takes a list of values instead of a
     single value.
 
 .. method:: QueryDict.lists()
@@ -546,9 +545,9 @@ In addition, ``QueryDict`` has the following methods:
 
 .. method:: QueryDict.dict()
 
-    Returns ``dict`` representation of ``QueryDict``. For every (key, list)
+    Returns a ``dict`` representation of ``QueryDict``. For every (key, list)
     pair in ``QueryDict``, ``dict`` will have (key, item), where item is one
-    element of the list, using same logic as :meth:`QueryDict.__getitem__()`::
+    element of the list, using the same logic as :meth:`QueryDict.__getitem__`::
 
         >>> q = QueryDict('a=1&a=3&a=5')
         >>> q.dict()
@@ -556,14 +555,14 @@ In addition, ``QueryDict`` has the following methods:
 
 .. method:: QueryDict.urlencode(safe=None)
 
-    Returns a string of the data in query-string format. Example::
+    Returns a string of the data in query string format. For example::
 
         >>> q = QueryDict('a=2&b=3&b=5')
         >>> q.urlencode()
         'a=2&b=3&b=5'
 
-    Optionally, urlencode can be passed characters which
+    Use the ``safe`` parameter to pass characters which don't require encoding.
-    do not require encoding. For example::
+    For example::
 
         >>> q = QueryDict(mutable=True)
         >>> q['next'] = '/a&b/'
@@ -577,7 +576,7 @@ In addition, ``QueryDict`` has the following methods:
 
 In contrast to :class:`HttpRequest` objects, which are created automatically by
 Django, :class:`HttpResponse` objects are your responsibility. Each view you
-write is responsible for instantiating, populating and returning an
+write is responsible for instantiating, populating, and returning an
 :class:`HttpResponse`.
 
 The :class:`HttpResponse` class lives in the :mod:`django.http` module.