From 8ebeb03740dad4d9edd65de88f82840a05070941 Mon Sep 17 00:00:00 2001
From: Victor Stinner <victor.stinner@gmail.com>
Date: Fri, 11 Jul 2014 23:47:40 +0200
Subject: asyncio: improve the documentation of servers

- Fix the documentation of Server.close(): it closes sockets
- Replace AbstractServer with Server
- Document Server.sockets attribute
---
 Doc/library/asyncio-eventloop.rst | 27 +++++++++++++++++++++------
 Doc/library/asyncio-stream.rst    | 21 +++++++++------------
 Lib/asyncio/base_events.py        |  4 +++-
 3 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index c82ea48..993a5de 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -263,8 +263,9 @@ Creating listening connections
 
 .. method:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
 
-   Create a TCP server bound to host and port. Return an
-   :class:`AbstractServer` object which can be used to stop the service.
+   Create a TCP server bound to host and port. Return a :class:`Server` object,
+   its :attr:`~Server.sockets` attribute contains created sockets. Use the
+   :meth:`Server.close` method to stop the server: close listening sockets.
 
    This method is a :ref:`coroutine <coroutine>`.
 
@@ -557,17 +558,31 @@ Debug mode
 Server
 ------
 
-.. class:: AbstractServer
+.. class:: Server
 
-   Abstract server returned by :func:`BaseEventLoop.create_server`.
+   Server listening on sockets.
+
+   Object created by the :meth:`BaseEventLoop.create_server` method and the
+   :func:`start_server` function. Don't instanciate the class directly.
 
    .. method:: close()
 
-      Stop serving.  This leaves existing connections open.
+      Stop serving: close all sockets and set the :attr:`sockets` attribute to
+      ``None``.
+
+      The server is closed asynchonously, use the :meth:`wait_closed` coroutine
+      to wait until the server is closed.
 
    .. method:: wait_closed()
 
-      A :ref:`coroutine <coroutine>` to wait until service is closed.
+      Wait until the :meth:`close` method completes.
+
+      This method is a :ref:`coroutine <coroutine>`.
+
+   .. attribute:: sockets
+
+      List of :class:`socket.socket` objects the server is listening to, or
+      ``None`` if the server is closed.
 
 
 Handle
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index f6b126d..81bd7f0 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -34,29 +34,26 @@ Stream functions
 
 .. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
 
-   Start a socket server, with a callback for each client connected.
+   Start a socket server, with a callback for each client connected. The return
+   value is the same as :meth:`~BaseEventLoop.create_server()`.
 
-   The first parameter, *client_connected_cb*, takes two parameters:
+   The *client_connected_cb* parameter is called with two parameters:
    *client_reader*, *client_writer*.  *client_reader* is a
    :class:`StreamReader` object, while *client_writer* is a
-   :class:`StreamWriter` object.  This parameter can either be a plain callback
-   function or a :ref:`coroutine function <coroutine>`; if it is a coroutine
-   function, it will be automatically wrapped in a future using the
-   :meth:`BaseEventLoop.create_task` method.
+   :class:`StreamWriter` object.  The *client_connected_cb* parameter can
+   either be a plain callback function or a :ref:`coroutine function
+   <coroutine>`; if it is a coroutine function, it will be automatically
+   wrapped in a future using the :meth:`BaseEventLoop.create_task` method.
 
    The rest of the arguments are all the usual arguments to
    :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.  The return value is the same as
-   :meth:`~BaseEventLoop.create_server()`.
+   common are positional *host* and *port*, with various optional keyword
+   arguments following.
 
    Additional optional keyword arguments are *loop* (to set the event loop
    instance to use) and *limit* (to set the buffer limit passed to the
    :class:`StreamReader`).
 
-   The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
-   a :class:`AbstractServer` object which can be used to stop the service.
-
    This function is a :ref:`coroutine <coroutine>`.
 
 .. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
index 10996d2..cab4462 100644
--- a/Lib/asyncio/base_events.py
+++ b/Lib/asyncio/base_events.py
@@ -110,6 +110,8 @@ class Server(events.AbstractServer):
             return
         self.sockets = None
         for sock in sockets:
+            # closing sockets will call asynchronously the _detach() method
+            # which calls _wakeup() for the last socket
             self._loop._stop_serving(sock)
         if self._active_count == 0:
             self._wakeup()
@@ -626,7 +628,7 @@ class BaseEventLoop(events.AbstractEventLoop):
                       reuse_address=None):
         """Create a TCP server bound to host and port.
 
-        Return an AbstractServer object which can be used to stop the service.
+        Return an Server object which can be used to stop the service.
 
         This method is a coroutine.
         """
-- 
cgit v0.12