Docs about getsockaddr and the ares resolver. Fixes #815.

[skip ci]

doc/dns.rst

@@ -6,7 +6,7 @@ gevent includes support for a pluggable hostname resolution system.
 Pluggable resolvers are (generally) intended to be cooperative.
 This pluggable resolution system is used automatically when the system
 is :mod:`monkey patched <gevent.monkey>`, and may be used manually
-through the :attr:`resolver attribute <gevent.Hub.resolver>` of the
+through the :attr:`resolver attribute <gevent.hub.Hub.resolver>` of the
 :class:`gevent.hub.Hub` or the corresponding methods in the
 :mod:`gevent.socket` module.
 

src/gevent/resolver_ares.py

@@ -23,10 +23,13 @@ class Resolver(object):
     resolution. c-ares is natively asynchronous at the socket level
     and so integrates well into gevent's event loop.
 
-    In comparison to :class:`gevent.resolver_thread.Resolver`, the
-    implementation is much more complex. In addition, there have been
-    reports of it not properly honoring certain system configurations.
-    However, because it does not use threads, it may scale better.
+    In comparison to :class:`gevent.resolver_thread.Resolver` (which
+    delegates to the native system resolver), the implementation is
+    much more complex. In addition, there have been reports of it not
+    properly honoring certain system configurations (for example, the
+    order in which IPv4 and IPv6 results are returned may not match
+    the threaded resolver). However, because it does not use threads,
+    it may scale better for applications that make many lookups.
 
     .. caution:: This module is considered extremely experimental on PyPy, and
        due to its implementation in cython, it may be slower. It may also lead to
@@ -211,6 +214,10 @@ class Resolver(object):
                     for socktype, proto in socktype_proto:
                         dest.append((AF_INET6, socktype, proto, '', sockaddr))
 
+        # As of 2016, some platforms return IPV6 first and some do IPV4 first,
+        # and some might even allow configuration of which is which. For backwards
+        # compatibility with earlier releases (but not necessarily resolver_thread!)
+        # we return 4 first. See https://github.com/gevent/gevent/issues/815 for more.
         result += result4 + result6
 
         if not result: