Update socket docs to clarify their duplication of stdlib interface; tone down...

Update socket docs to clarify their duplication of stdlib interface; tone down the warnings. [skip ci]

doc/gevent.socket.rst

@@ -8,24 +8,30 @@ items in the standard :mod:`socket` module exactly, but the
 synchronous functions in this module only block the current greenlet
 and let the others run.
 
-.. warning:: gevent's sockets have thread affinity. That is, they can
-             only be used from the operating system thread that
-             created them (any greenlet in that thread can use the
-             socket). The results of attempting to use the socket in
-             another thread (for example, passing it to the
-             threadpool) are not defined (but one common outcome is a
-             :exc:`~gevent.hub.LoopExit` exception).
+.. tip:: gevent's sockets, like most gevent objects, have thread
+         affinity. That is, they can only be used from the operating
+         system thread that created them (any greenlet in that thread
+         can use the socket). The results of attempting to use the
+         socket in another thread (for example, passing it to the
+         threadpool) are not defined (but one common outcome is a
+         :exc:`~gevent.hub.LoopExit` exception).
 
 For convenience, exceptions (like :class:`error <socket.error>` and
 :class:`timeout <socket.timeout>`) as well as the constants from the
-:mod:`socket` module are imported into this module.
+:mod:`socket` module are imported into this module. In almost all
+cases one can simply replace ``import socket`` with ``from gevent
+import socket`` to start using cooperative sockets with no other
+changes (or use :func:`gevent.monkey.patch_socket` at startup if code
+changes are not desired or possible).
 
+Standard Library Interface
+==========================
 
 The exact API exposed by this module varies depending on what version
 of Python you are using. The documents below describe the API for
 Python 2 and Python 3, respectively.
 
-.. caution:: All the described APIs should be imported from
+.. note:: All the described APIs should be imported from
    ``gevent.socket``, and *not* from their implementation modules.
    Their organization is an implementation detail that may change at
    any time.

gevent/_socket2.py

@@ -94,6 +94,10 @@ class socket(object):
     """
     gevent `socket.socket <https://docs.python.org/2/library/socket.html#socket-objects>`_
     for Python 2.
+
+    This object should have the same API as the standard library socket linked to above. Not all
+    methods are specifically documented here; when they are they may point out a difference
+    to be aware of or may document a method the standard library does not.
     """
 
     def __init__(self, family=AF_INET, type=SOCK_STREAM, proto=0, _sock=None):
@@ -454,9 +458,9 @@ class socket(object):
             self.hub.cancel_wait(self._write_event, cancel_wait_ex)
         self._sock.shutdown(how)
 
-    family = property(lambda self: self._sock.family, doc="the socket family")
-    type = property(lambda self: self._sock.type, doc="the socket type")
-    proto = property(lambda self: self._sock.proto, doc="the socket protocol")
+    family = property(lambda self: self._sock.family)
+    type = property(lambda self: self._sock.type)
+    proto = property(lambda self: self._sock.proto)
 
     # delegate the functions that we haven't implemented to the real socket object
 

gevent/_socket3.py

@@ -53,6 +53,10 @@ class socket(object):
     """
     gevent `socket.socket <https://docs.python.org/3/library/socket.html#socket-objects>`_
     for Python 3.
+
+    This object should have the same API as the standard library socket linked to above. Not all
+    methods are specifically documented here; when they are they may point out a difference
+    to be aware of or may document a method the standard library does not.
     """
 
     # Subclasses can set this to customize the type of the