From: Ben Darnell <ben@bendarnell.com>
Date: Tue, 31 Dec 2013 22:50:12 +0000 (-0500)
Subject: Doc updates.
X-Git-Tag: v3.2.0b2~11
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=be70cb085ba57297cbde219e206d05694f6ea7d9;p=thirdparty%2Ftornado.git

Doc updates.

* Version-added tags
* Add some missing methods
* Ignore asyncio module for coverage reports
* Work around a sphinx 1.2 regression
---

diff --git a/docs/asyncio.rst b/docs/asyncio.rst
index 98599a7db..d09650661 100644
--- a/docs/asyncio.rst
+++ b/docs/asyncio.rst
@@ -3,6 +3,8 @@
 
 .. module:: tornado.platform.asyncio
 
+.. versionadded:: 3.2
+
 This module integrates Tornado with the ``asyncio`` module introduced
 in Python 3.4 (and available `as a separate download
 <https://pypi.python.org/pypi/asyncio>`_ for Python 3.3).  This makes
diff --git a/docs/conf.py b/docs/conf.py
index a091fa7ec..46ca60e16 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,8 +25,14 @@ default_role = 'py:obj'
 autodoc_member_order = "bysource"
 autoclass_content = "both"
 
+# Without this line sphinx includes a copy of object.__init__'s docstring
+# on any class that doesn't define __init__.
+# https://bitbucket.org/birkenfeld/sphinx/issue/1337/autoclass_content-both-uses-object__init__
+autodoc_docstring_signature = False
+
 coverage_skip_undoc_in_source = True
 coverage_ignore_modules = [
+    "tornado.platform.asyncio",
     "tornado.platform.twisted",
     ]
 # I wish this could go in a per-module file...
diff --git a/docs/web.rst b/docs/web.rst
index b62f2b57e..104f686eb 100644
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -92,6 +92,7 @@
       The `Application` object serving this request
 
    .. automethod:: RequestHandler.async_callback
+   .. automethod:: RequestHandler.check_etag_header
    .. automethod:: RequestHandler.check_xsrf_cookie
    .. automethod:: RequestHandler.compute_etag
    .. automethod:: RequestHandler.create_template_loader
@@ -105,6 +106,7 @@
    .. automethod:: RequestHandler.on_connection_close
    .. automethod:: RequestHandler.require_setting
    .. automethod:: RequestHandler.reverse_url
+   .. automethod:: RequestHandler.set_etag_header
    .. autoattribute:: RequestHandler.settings
    .. automethod:: RequestHandler.static_url
    .. automethod:: RequestHandler.xsrf_form_html
diff --git a/tornado/auth.py b/tornado/auth.py
index f2080f1e9..0881b0518 100644
--- a/tornado/auth.py
+++ b/tornado/auth.py
@@ -949,7 +949,10 @@ class GoogleMixin(OpenIdMixin, OAuthMixin):
 
 
 class GoogleOAuth2Mixin(OAuth2Mixin):
-    """Google authentication using OAuth2."""
+    """Google authentication using OAuth2.
+
+    .. versionadded:: 3.2
+    """
     _OAUTH_AUTHORIZE_URL = "https://accounts.google.com/o/oauth2/auth"
     _OAUTH_ACCESS_TOKEN_URL = "https://accounts.google.com/o/oauth2/token"
     _OAUTH_NO_CALLBACKS = False
diff --git a/tornado/escape.py b/tornado/escape.py
index 302e556f1..95c0f24e8 100644
--- a/tornado/escape.py
+++ b/tornado/escape.py
@@ -55,7 +55,16 @@ _XHTML_ESCAPE_DICT = {'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;',
 
 
 def xhtml_escape(value):
-    """Escapes a string so it is valid within HTML or XML."""
+    """Escapes a string so it is valid within HTML or XML.
+
+    Escapes the characters ``<``, ``>``, ``"``, ``'``, and ``&``.
+    When used in attribute values the escaped strings must be enclosed
+    in quotes.
+
+    .. versionchanged:: 3.2
+
+       Added the single quote to the list of escaped characters.
+    """
     return _XHTML_ESCAPE_RE.sub(lambda match: _XHTML_ESCAPE_DICT[match.group(0)],
                                 to_basestring(value))
 
diff --git a/tornado/log.py b/tornado/log.py
index bc6898c82..48532b189 100644
--- a/tornado/log.py
+++ b/tornado/log.py
@@ -84,6 +84,10 @@ class LogFormatter(logging.Formatter):
           message text.
         :arg string datefmt: Datetime format.
           Used for formatting ``(asctime)`` placeholder in ``prefix_fmt``.
+
+        .. versionchanged:: 3.2
+
+           Added ``prefix_fmt`` and ``datefmt`` arguments.
         """
         self.__prefix_fmt = prefix_fmt if prefix_fmt is not None else self.DEFAULT_PREFIX_FORMAT
         datefmt = datefmt if datefmt is not None else self.DEFAULT_DATE_FORMAT
diff --git a/tornado/web.py b/tornado/web.py
index 65a76cd47..7d29c3834 100644
--- a/tornado/web.py
+++ b/tornado/web.py
@@ -516,6 +516,10 @@ class RequestHandler(object):
 
         See `clear_cookie` for more information on the path and domain
         parameters.
+
+        .. versionchanged:: 3.2
+
+           Added the ``path`` and ``domain`` parameters.
         """
         for name in self.request.cookies:
             self.clear_cookie(name, path=path, domain=domain)