monkey: add __doc__

gevent/monkey.py

 # Copyright (c) 2009-2010 Denis Bilenko. See LICENSE for details.
+"""Make the standard library cooperative.
+
+The functions in this module patch parts of the standard library with compatible cooperative counterparts
+from :mod:`gevent` package.
+
+To patch an individual module call the corresponding ``patch_*`` function. For example, to patch
+socket module only, call :func:`patch_socket`. To patch all default modules, call ``gevent.monkey.patch_all()``.
+
+Monkey can also patch thread and threading to become greenlet-based. So :func:`thread.start_new_thread`
+starts a new greenlet instead and :class:`threading.local` becomes a greenlet-local storage.
+
+Monkey patches:
+
+* :mod:`socket` module -- :func:`patch_socket`
+
+  - :class:`socket`
+  - :class:`SocketType`
+  - :func:`socketpair`
+  - :func:`fromfd`
+  - :func:`ssl` and :class:`sslerror`
+  - :func:`socket.getaddrinfo`
+  - :func:`socket.gethostbyname`
+  - It is possible to disable dns patching by passing ``dns=False`` to :func:`patch_socket` of :func:`patch_all`
+  - If ssl is not available (Python < 2.6 without ``ssl`` and ``PyOpenSSL`` packages installed) then :func:`ssl` is removed from the target :mod:`socket` module.
+
+* :mod:`ssl` module -- :func:`patch_ssl`
+
+  - :class:`SSLSocket`
+  - :func:`wrap_socket`
+  - :func:`get_server_certificate`
+  - :func:`sslwrap_simple`
+
+* :mod:`os` module -- :func:`patch_os`
+
+  - :func:`fork`
+
+* :mod:`time` module -- :func:`patch_time`
+
+  - :func:`time`
+
+* :mod:`select` module -- :func:`patch_select`
+
+  - :func:`select`
+  - Removes polling mechanisms that :mod:`gevent.select` does not simulate: poll, epoll, kqueue, kevent
+
+* :mod:`thread` and :mod:`threading` modules -- :func:`patch_thread`
+
+  - Become greenlet-based.
+  - :func:`get_ident`
+  - :func:`start_new_thread`
+  - :class:`LockType`
+  - :func:`allocate_lock`
+  - :func:`exit`
+  - :func:`stack_size`
+  - thread-local storage becomes greenlet-local storage
+"""
 
 import sys
 
@@ -6,6 +62,7 @@ noisy = True
 
 
 def patch_os():
+    """Replace :func:`os.fork` with :func:`gevent.fork`."""
     try:
         from gevent.hub import fork
     except ImportError:
@@ -15,27 +72,17 @@ def patch_os():
 
 
 def patch_time():
+    """Replace :func:`time.sleep` with :func:`gevent.sleep`."""
     from gevent.hub import sleep
     _time = __import__('time')
     _time.sleep = sleep
 
 
 def patch_thread(threading=True, _threading_local=True):
-    """Patch the standard :mod:`thread` module to make it greenlet-based.
-
-    Patch the following names in :mod:`thread` module:
-    - :func:`get_ident`
-    - :func:`start_new_thread`
-    - :class:`LockType`
-    - :func:`allocate_lock`
-    - :func:`exit`
-    - :func:`stack_size`
-    - :class:`_local`
-
+    """Replace the standard :mod:`thread` module to make it greenlet-based.
     If *threading* is true (the default), also patch ``threading.local``.
     If *_threading_local* is true (the default), also patch ``_threading_local.local``.
     """
-
     from gevent import thread as green_thread
     thread = __import__('thread')
     if thread.exit is not green_thread.exit:
@@ -59,6 +106,10 @@ def patch_thread(threading=True, _threading_local=True):
 
 
 def patch_socket(dns=True, aggressive=True):
+    """Replace the standard socket object with gevent's cooperative sockets.
+    
+    If *dns* is true, also patch dns functions in :mod:`socket`.
+    """
     from gevent import socket
     _socket = __import__('socket')
     _socket.socket = socket.socket
@@ -101,6 +152,10 @@ def patch_ssl():
 
 
 def patch_select(aggressive=False):
+    """Replace :func:`select.select` with :func:`gevent.select.select`.
+
+    If aggressive is true (the default), also remove other blocking functions the :mod:`select`.
+    """
     from gevent.select import select
     _select = __import__('select')
     globals()['_select_select'] = _select.select
@@ -116,6 +171,7 @@ def patch_select(aggressive=False):
 
 
 def patch_all(socket=True, dns=True, time=True, select=True, thread=True, os=True, ssl=True, aggressive=True):
+    """Do all of the default monkey patching (calls every other function in this module."""
     # order is important
     if os:
         patch_os()