update comments and docs. [skip ci]

changelog.rst

@@ -4,7 +4,7 @@
 
 .. currentmodule:: gevent
 
-1.1rc6 (unreleased)
+1.1.0 (unreleased)
 ===================
 
 - Python 3: A monkey-patched :class:`threading.RLock` now properly
@@ -13,15 +13,16 @@
   None). The ``acquire`` method also raises the same :exc:`ValueError`
   exceptions that the standard library does for invalid parameters.
   Reported in :issue:`750` by Joy Zheng.
-- Fix a race condition in :class:`~gevent.event.Event` that
-  made it return ``False`` when the event was set and cleared by the
-  same greenlet before allowing a switch to the waiting greenlets.
-  (Found by the 3.4 and 3.5 standard library test suites; the same as
-  Python `bug 13502`_).
+- Fix a race condition in :class:`~gevent.event.Event` that made it
+  return ``False`` when the event was set and cleared by the same
+  greenlet before allowing a switch to already waiting greenlets. (Found
+  by the 3.4 and 3.5 standard library test suites; the same as Python
+  `bug 13502`_. Note that the Python 2 standard library still has this
+  race condition.)
 - :class:`~gevent.event.Event` and :class:`~.AsyncResult` now wake
   waiting greenlets in the same (unspecified) order. Previously,
   ``AsyncResult`` tended to use a FIFO order, but this was never
-  guaranteed.
+  guaranteed. Both classes also use less per-instance memory.
 
 .. _bug 13502: http://bugs.python.org/issue13502
 
@@ -55,7 +56,7 @@
   each request, reducing overhead.
 - Python 2: Under 2.7.9 and above (or when the PEP 466 SSL interfaces
   are available), perform the same hostname validation that the
-  standard library does; previously some cases were ignored. Also,
+  standard library does; previously this was skipped. Also,
   reading, writing, or handshaking a closed
   :class:`~ssl.SSLSocket` now raises the same :exc:`ValueError`
   the standard library does, instead of an :exc:`AttributeError`.

gevent/__init__.py

@@ -15,10 +15,10 @@ _version_info = namedtuple('version_info',
 
 #: The programatic version identifier. The fields have (roughly) the
 #: same meaning as :data:`sys.version_info`
-version_info = _version_info(1, 1, 0, 'rc', '6')
+version_info = _version_info(1, 1, 0, 'final', 0)
 
 #: The human-readable PEP 440 version identifier
-__version__ = '1.1rc6.dev0'
+__version__ = '1.1.0.dev0'
 
 
 __all__ = ['get_hub',

gevent/_socket2.py

@@ -91,6 +91,9 @@ timeout_default = object()
 
 
 class socket(object):
+    """
+    gevent socket object.
+    """
 
     def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, _sock=None):
         if _sock is None:
@@ -456,10 +459,10 @@ class socket(object):
 
     # delegate the functions that we haven't implemented to the real socket object
 
-    _s = ("def %s(self, *args): return self._sock.%s(*args)\n\n"
-          "%s.__doc__ = _realsocket.%s.__doc__\n")
+    _s = "def %s(self, *args): return self._sock.%s(*args)\n\n"
+
     for _m in set(_socketmethods) - set(locals()):
-        exec(_s % (_m, _m, _m, _m))
+        exec(_s % (_m, _m,))
     del _m, _s
 
     if PYPY:

gevent/_socket3.py

@@ -51,6 +51,9 @@ _closedsocket.close()
 
 
 class socket(object):
+    """
+    gevent socket object.
+    """
 
     _gevent_sock_class = _wrefsocket
 
@@ -175,12 +178,13 @@ class socket(object):
 
     def makefile(self, mode="r", buffering=None, *,
                  encoding=None, errors=None, newline=None):
-        """makefile(...) -> an I/O stream connected to the socket
+        """Return an I/O stream connected to the socket
 
         The arguments are as for io.open() after the filename,
         except the only mode characters supported are 'r', 'w' and 'b'.
-        The semantics are similar too.  (XXX refactor to share code?)
+        The semantics are similar too.
         """
+        # (XXX refactor to share code?)
         for c in mode:
             if c not in {"r", "w", "b"}:
                 raise ValueError("invalid mode %r (only r, w, b allowed)")
@@ -480,6 +484,10 @@ class socket(object):
         bytes which were sent.
         The socket must be of SOCK_STREAM type.
         Non-blocking sockets are not supported.
+
+        .. versionadded:: 1.1rc4
+           Added in Python 3.5, but available under all Python 3 versions in
+           gevent.
         """
         return self._sendfile_use_send(file, offset, count)
 
@@ -497,8 +505,10 @@ class socket(object):
 
             def set_inheritable(self, inheritable):
                 os.set_inheritable(self.fileno(), inheritable)
-        get_inheritable.__doc__ = "Get the inheritable flag of the socket"
-        set_inheritable.__doc__ = "Set the inheritable flag of the socket"
+        _added = "\n\n.. versionadded:: 1.1rc4 Added in Python 3.4"
+        get_inheritable.__doc__ = "Get the inheritable flag of the socket" + _added
+        set_inheritable.__doc__ = "Set the inheritable flag of the socket" + _added
+        del _added
 
 
 if sys.version_info[:2] == (3, 4) and sys.version_info[:3] <= (3, 4, 2):

greentest/test_threading_2.py

@@ -9,10 +9,12 @@ from gevent.thread import allocate_lock as Lock
 import threading
 threading.Event = Event
 threading.Lock = Lock
-# XXX: We're completely patching around the allocate_lock
+# NOTE: We're completely patching around the allocate_lock
 # patch we try to do with RLock; our monkey patch doesn't
-# behave this way, why do we do it in tests? Save it so we can
-# at least access it sometimes.
+# behave this way, but we do it in tests to make sure that
+# our RLock implementation behaves correctly by itself.
+# However, we must test the patched version too, so make it
+# available.
 threading.NativeRLock = threading.RLock
 threading.RLock = RLock
 threading.Semaphore = Semaphore
@@ -528,8 +530,8 @@ class RLockTests(lock_tests.RLockTests):
     locktype = staticmethod(threading.RLock)
 
 class NativeRLockTests(lock_tests.RLockTests):
-    # XXX: See comments at the top of the file for the difference
-    # between this and RLockTests, and why its weird.
+    # See comments at the top of the file for the difference
+    # between this and RLockTests, and why they both matter
     locktype = staticmethod(threading.NativeRLock)
 
 class EventTests(lock_tests.EventTests):