Some minor documentation cleanup for intro and basics. Prepping for some re-org.

doc/conf.py

@@ -243,3 +243,7 @@ import gevent.socket
 for item in gevent.socket.__all__[:]:
     if getattr(gevent.socket, item) is getattr(socket, item, None):
         gevent.socket.__all__.remove(item)
+
+if not hasattr(gevent.socket, '_fileobject'):
+    # Python 3 building Python 2 docs.
+    gevent.socket._fileobject = object()

doc/gevent.rst

@@ -13,18 +13,20 @@ Greenlet objects
 
 :class:`Greenlet` is a light-weight cooperatively-scheduled execution unit.
 
-To start a new greenlet, pass the target function and its arguments to :class:`Greenlet` constructor and call :meth:`start`:
+To start a new greenlet, pass the target function and its arguments to
+:class:`Greenlet` constructor and call :meth:`Greenlet.start`:
 
 >>> g = Greenlet(myfunction, 'arg1', 'arg2', kwarg1=1)
 >>> g.start()
 
-or use classmethod :meth:`spawn` which is a shortcut that does the same:
+or use classmethod :meth:`Greenlet.spawn` which is a shortcut that
+does the same:
 
 >>> g = Greenlet.spawn(myfunction, 'arg1', 'arg2', kwarg1=1)
 
 To subclass a :class:`Greenlet`, override its ``_run()`` method and
-call ``Greenlet.__init__(self)`` in :meth:`__init__`: It also a good
-idea to override :meth:`__str__`: if :meth:`_run` raises an exception,
+call ``Greenlet.__init__(self)`` in the subclass ``__init__``.  It also a good
+idea to override :meth:`Greenlet.__str__`: if ``_run`` raises an exception,
 its string representation will be printed after the traceback it
 generated.
 
@@ -37,9 +39,11 @@ generated.
 .. autoattribute:: Greenlet.exception
 .. autoattribute:: Greenlet.minimal_ident
 .. autoattribute:: Greenlet.name
+.. autoattribute:: Greenlet.dead
 
 .. rubric:: Methods
 
+.. automethod:: Greenlet.spawn
 .. automethod:: Greenlet.ready
 .. automethod:: Greenlet.successful
 .. automethod:: Greenlet.start
@@ -52,6 +56,7 @@ generated.
 .. automethod:: Greenlet.link_exception(callback)
 .. automethod:: Greenlet.rawlink
 .. automethod:: Greenlet.unlink
+.. automethod:: Greenlet.__str__
 
 Boolean Contexts
 ----------------
@@ -65,12 +70,12 @@ It's possible to use it like this::
     >>> while g:
            # do something while g is alive
 
-The Greenlet's ``__nonzero__`` is an improvement on greenlet's
-``__nonzero__``. The greenlet's :meth:`__nonzero__
-<greenlet.greenlet.__nonzero__>` returns False if greenlet has not
-been switched to yet or is already dead. While the latter is OK, the
-former is not good, because a just spawned Greenlet has not been
-switched to yet and thus would evaluate to False.
+The Greenlet's boolean value is an improvement on the raw
+:class:`greenlet's <greenlet.greenlet>` boolean value. The raw
+greenlet's boolean value returns False if the greenlet has not been
+switched to yet or is already dead. While the latter is OK, the former
+is not good, because a just spawned Greenlet has not been switched to
+yet and thus would evaluate to False.
 
 Raw greenlet Methods
 --------------------
@@ -86,6 +91,10 @@ __ https://greenlet.readthedocs.io/en/latest/#instantiation
 .. _switching: https://greenlet.readthedocs.io/en/latest/#switching
 .. _throw: https://greenlet.readthedocs.io/en/latest/#methods-and-attributes-of-greenlets
 
+.. class:: greenlet.greenlet
+
+    The base class from which `Greenlet` descends.
+
 .. exception:: GreenletExit
 
     A special exception that kills the greenlet silently.
@@ -192,3 +201,6 @@ Configuration
 =============
 
 .. autoclass:: gevent._config.Config
+
+..  LocalWords:  Greenlet GreenletExit Greenlet's greenlet's
+..  LocalWords:  automethod

doc/gevent.socket.rst

@@ -38,6 +38,14 @@ Python 2 and Python 3, respectively.
    Their organization is an implementation detail that may change at
    any time.
 
+.. autofunction:: gevent.socket.gethostbyname
+
+.. class:: socket
+
+    The cooperative socket object. See the version documentation for
+    specifics.
+
+
 .. toctree::
 
    Python 3 interface <gevent._socket3>

doc/gevent.ssl.rst

@@ -2,6 +2,8 @@
  :mod:`gevent.ssl` -- Secure Sockets Layer (SSL/TLS) module
 ====================================================================
 
+.. module:: gevent.ssl
+
 This module provides SSL/TLS operations and some related functions. The
 API of the functions and classes matches the API of the corresponding
 items in the standard :mod:`ssl` module exactly, but the
@@ -17,6 +19,11 @@ Python 3, Python 2.7.9 and above, and Python 2.7.8 and below, respectively.
    Their organization is an implementation detail that may change at
    any time.
 
+.. class:: SSLObject
+
+    The gevent-cooperative SSL object. See the version-specific
+    documentation for details.
+
 .. toctree::
 
    Python 3 interface <gevent._ssl3>

src/gevent/_ssl2.py

 # Wrapper module for _ssl. Written by Bill Janssen.
 # Ported to gevent by Denis Bilenko.
-"""SSL wrapper for socket objects on Python 2.7.8 and below.
+"""
+SSL wrapper for socket objects on Python 2.7.8 and below.
 
 For the documentation, refer to :mod:`ssl` module manual.
 
 This module implements cooperative SSL socket wrappers.
+
+.. deprecated:: 1.3
+   This module is not secure. Support for Python versions
+   with only this level of SSL will be dropped in gevent 1.4.
 """
 
 from __future__ import absolute_import

src/gevent/greenlet.py

@@ -367,6 +367,7 @@ class Greenlet(greenlet):
         # oops - pypy's .dead relies on __nonzero__ which we overriden above
         @property
         def dead(self):
+            "Boolean indicating that the greenlet is dead and will not run again."
             if self._greenlet__main:
                 return False
             if self.__start_cancelled_by_kill() or self.__started_but_aborted():
@@ -376,6 +377,7 @@ class Greenlet(greenlet):
     else:
         @property
         def dead(self):
+            "Boolean indicating that the greenlet is dead and will not run again."
             return self.__start_cancelled_by_kill() or self.__started_but_aborted() or greenlet.dead.__get__(self)
 
     def __never_started_or_killed(self):