More DNS docs [skip ci]

doc/whatsnew_1_3.rst

@@ -13,7 +13,7 @@ on platform support, standard library compatibility, security, bug
 fixes and consistency.
 
 Platform Support
-========================
+================
 
 gevent 1.2 supports Python 2.7, 3.4, 3.5 and 3.6 on the CPython
 (`python.org`_) interpreter. It also supports `PyPy2`_ 4.0.1 and above
@@ -40,70 +40,40 @@ Bug Fixes
 Since 1.1.2, gevent 1.2 contains over 240 commits from nine different
 dozen contributors. About two dozen pull requests were merged.
 
-Improved subprocess support
-===========================
-
-In gevent 1.1, subprocess monkey-patching was on by default for the
-first time. Over time this led to discovery of a few issues and corner
-cases that have been fixed in 1.2.
-
-- Setting SIGCHLD to SIG_IGN or SIG_DFL after :mod:`gevent.subprocess`
-  had been used previously could not be reversed, causing
-  ``Popen.wait`` and other calls to hang. Now, if SIGCHLD has been
-  ignored, the next time :mod:`gevent.subprocess` is used this will be
-  detected and corrected automatically. (This potentially leads to
-  issues with :func:`os.popen` on Python 2, but the signal can always
-  be reset again. Mixing the low-level process handling calls,
-  low-level signal management and high-level use of
-  :mod:`gevent.subprocess` is tricky.) Reported in :issue:`857` by
-  Chris Utz.
-- ``Popen.kill`` and ``send_signal`` no longer attempt to send signals
-  to processes that are known to be exited.
-- The :func:`gevent.os.waitpid` function is cooperative in more
-  circumstances. Reported in :issue:`878` by Heungsub Lee.
+New Pure-Python DNS Resolver
+============================
+
+WRITE ME.
 
 API Additions
 =============
 
 Numerous APIs offer slightly expanded functionality in this version.
-Look for "changed in version 1.2" or "added in version 1.2" throughout
+Look for "changed in version 1.3" or "added in version 1.3" throughout
 the documentation for specifics.
 
-Of particular note, several backwards compatible updates to the
-subprocess module have been backported from Python 3 to Python 2,
-making :mod:`gevent.subprocess` smaller, easier to maintain and in
-some cases safer, while letting gevent clients use the updated APIs
-even on older versions of Python.
-
-If ``concurrent.futures`` is available (Python 3, or if the Python 2
-backport has been installed), then the class
-:class:`gevent.threadpool.ThreadPoolExecutor` is defined to create an
-executor that always uses native threads, even when the system is
-monkey-patched.
 
 Library Updates
 ===============
 
-The two C libraries that are bundled with gevent have been updated.
-libev has been updated from 4.20 to 4.23 (`libev release notes`_) and
-c-ares has been updated from 1.10.0 to 1.12.0 (`c-ares release notes`_).
+One of the C libraries that are bundled with gevent have been updated.
+c-ares has been updated from 1.12.0 to 1.13.0 (`c-ares release notes`_).
 
 
-.. _libev release notes: https://github.com/gevent/gevent/blob/master/deps/libev/Changes
 .. _c-ares release notes: https://c-ares.haxx.se/changelog.html
 
 Compatibility
 =============
 
-This release is intended to be compatible with 1.1.x with no changes
+This release is intended to be compatible with 1.2.x with no changes
 to client source code, so long as only non-deprecated and supported
 interfaces were used (as always, internal, non-documented
 implementation details may have changed).
 
-In particular the deprecated ``gevent.coros`` module has been removed
-and ``gevent.corecext`` and ``gevent.corecffi`` have also been removed.
+The :doc:`resolvers <dns>` have been refactored. As a result,
+``gevent.ares``, ``gevent.resolver_ares`` and
+``gevent.resolver_thread`` have been deprecated. Choosing a resolver
+by alias (e.g., 'thread') in the ``GEVENT_RESOLVER`` environment
+variable continues to work as before.
 
-For security, ``gevent.pywsgi`` no longer accepts incoming headers
-containing an underscore, and header values passed to
-``start_response`` cannot contain a carriage return or newline. See
-:issue:`819` and :issue:`775`, respectively.
+TODO: Remove deprecated gevent.wsgi package.

src/gevent/resolver/dnspython.py

@@ -155,6 +155,9 @@ class Resolver(AbstractResolver):
         Windows). There are some measures in place to be able to resolve
         ``localhost`` related names and addresses through the system resolver.
 
+        Many of the same caveats about DNS results apply here as are documented
+        for :class:`gevent.resolver.ares.Resolver`.
+
     .. caution::
 
         This resolver is experimental. It may be removed or modified in

src/gevent/resolver/thread.py

@@ -35,7 +35,7 @@ class Resolver(object):
         some reports of long delays, slow performance or even hangs,
         particularly in long-lived programs that make many, many DNS
         requests. If you suspect that may be happening to you, try the
-        ares resolver (and submit a bug report).
+        dnspython or ares resolver (and submit a bug report).
     """
     def __init__(self, hub=None):
         if hub is None: