Tweak the socket module doc layout

1 files changed, 86 insertions, 64 deletions

diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 82400b7..3bd1c31 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -138,9 +138,12 @@ generalization of this based on timeouts is supported through
 Module contents
 ---------------
 
-The module :mod:`socket` exports the following constants and functions:
+The module :mod:`socket` exports the following elements.
 
 
+Exceptions
+^^^^^^^^^^
+
 .. exception:: error
 
    A deprecated alias of :exc:`OSError`.
@@ -186,6 +189,10 @@ The module :mod:`socket` exports the following constants and functions:
    .. versionchanged:: 3.3
       This class was made a subclass of :exc:`OSError`.
 
+
+Constants
+^^^^^^^^^
+
 .. data:: AF_UNIX
           AF_INET
           AF_INET6
@@ -290,6 +297,43 @@ The module :mod:`socket` exports the following constants and functions:
    this platform.
 
 
+Functions
+^^^^^^^^^
+
+Creating sockets
+''''''''''''''''
+
+The following functions all create :ref:`socket objects <socket-objects>`.
+
+
+.. function:: socket([family[, type[, proto]]])
+
+   Create a new socket using the given address family, socket type and protocol
+   number.  The address family should be :const:`AF_INET` (the default),
+   :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
+   socket type should be :const:`SOCK_STREAM` (the default),
+   :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
+   constants. The protocol number is usually zero and may be omitted in that
+   case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`.
+
+   .. versionchanged:: 3.3
+      The AF_CAN family was added.
+      The AF_RDS family was added.
+
+
+.. function:: socketpair([family[, type[, proto]]])
+
+   Build a pair of connected socket objects using the given address family, socket
+   type, and protocol number.  Address family, socket type, and protocol number are
+   as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
+   if defined on the platform; otherwise, the default is :const:`AF_INET`.
+   Availability: Unix.
+
+   .. versionchanged:: 3.2
+      The returned socket objects now support the whole socket API, rather
+      than a subset.
+
+
 .. function:: create_connection(address[, timeout[, source_address]])
 
    Connect to a TCP service listening on the Internet *address* (a 2-tuple
@@ -316,6 +360,40 @@ The module :mod:`socket` exports the following constants and functions:
       support for the :keyword:`with` statement was added.
 
 
+.. function:: fromfd(fd, family, type[, proto])
+
+   Duplicate the file descriptor *fd* (an integer as returned by a file object's
+   :meth:`fileno` method) and build a socket object from the result.  Address
+   family, socket type and protocol number are as for the :func:`.socket` function
+   above. The file descriptor should refer to a socket, but this is not checked ---
+   subsequent operations on the object may fail if the file descriptor is invalid.
+   This function is rarely needed, but can be used to get or set socket options on
+   a socket passed to a program as standard input or output (such as a server
+   started by the Unix inet daemon).  The socket is assumed to be in blocking mode.
+
+
+.. function:: fromshare(data)
+
+   Instantiate a socket from data obtained from the :meth:`socket.share`
+   method.  The socket is assumed to be in blocking mode.
+
+   Availability: Windows.
+
+   .. versionadded:: 3.3
+
+
+.. data:: SocketType
+
+   This is a Python type object that represents the socket object type. It is the
+   same as ``type(socket(...))``.
+
+
+Other functions
+'''''''''''''''
+
+The :mod:`socket` module also offers various network-related services:
+
+
 .. function:: getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)
 
    Translate the *host*/*port* argument into a sequence of 5-tuples that contain
@@ -445,46 +523,6 @@ The module :mod:`socket` exports the following constants and functions:
    ``'udp'``, otherwise any protocol will match.
 
 
-.. function:: socket([family[, type[, proto]]])
-
-   Create a new socket using the given address family, socket type and protocol
-   number.  The address family should be :const:`AF_INET` (the default),
-   :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The
-   socket type should be :const:`SOCK_STREAM` (the default),
-   :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_``
-   constants. The protocol number is usually zero and may be omitted in that
-   case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`.
-
-   .. versionchanged:: 3.3
-      The AF_CAN family was added.
-      The AF_RDS family was added.
-
-
-.. function:: socketpair([family[, type[, proto]]])
-
-   Build a pair of connected socket objects using the given address family, socket
-   type, and protocol number.  Address family, socket type, and protocol number are
-   as for the :func:`.socket` function above. The default family is :const:`AF_UNIX`
-   if defined on the platform; otherwise, the default is :const:`AF_INET`.
-   Availability: Unix.
-
-   .. versionchanged:: 3.2
-      The returned socket objects now support the whole socket API, rather
-      than a subset.
-
-
-.. function:: fromfd(fd, family, type[, proto])
-
-   Duplicate the file descriptor *fd* (an integer as returned by a file object's
-   :meth:`fileno` method) and build a socket object from the result.  Address
-   family, socket type and protocol number are as for the :func:`.socket` function
-   above. The file descriptor should refer to a socket, but this is not checked ---
-   subsequent operations on the object may fail if the file descriptor is invalid.
-   This function is rarely needed, but can be used to get or set socket options on
-   a socket passed to a program as standard input or output (such as a server
-   started by the Unix inet daemon).  The socket is assumed to be in blocking mode.
-
-
 .. function:: ntohl(x)
 
    Convert 32-bit positive integers from network to host byte order.  On machines
@@ -680,22 +718,6 @@ The module :mod:`socket` exports the following constants and functions:
    .. versionadded:: 3.3
 
 
-.. function:: fromshare(data)
-
-   Instantiate a socket from data obtained from :meth:`~socket.share`.
-   The socket is assumed to be in blocking mode.
-
-   Availability: Windows.
-
-   .. versionadded:: 3.3
-
-
-.. data:: SocketType
-
-   This is a Python type object that represents the socket object type. It is the
-   same as ``type(socket(...))``.
-
-
 .. _socket-objects:
 
 Socket Objects
@@ -1106,14 +1128,14 @@ to sockets.
 
 .. method:: socket.share(process_id)
 
-    :platform: Windows
+   Duplicate a socket and prepare it for sharing with a target process.  The
+   target process must be provided with *process_id*.  The resulting bytes object
+   can then be passed to the target process using some form of interprocess
+   communication and the socket can be recreated there using :func:`fromshare`.
+   Once this method has been called, it is safe to close the socket since
+   the operating system has already duplicated it for the target process.
 
-    Duplacet a socket and prepare it for sharing with a target process.  The
-    target process must be provided with *process_id*.  The resulting bytes object
-    can then be passed to the target process using some form of interprocess
-    communication and the socket can be recreated there using :func:`fromshare`.
-    Once this method has been called, it is safe to close the socket since
-    the operating system has already duplicated it for the target process.
+   Availability: Windows.
 
    .. versionadded:: 3.3