bpo-33736: Improve the documentation of asyncio stream APIs (GH-7326)

3 files changed, 73 insertions, 35 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index a38dab0..f5fd094 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -445,7 +445,7 @@ Creating connections
 
    .. versionchanged:: 3.7
 
-      The *path* parameter can now be a :class:`~pathlib.Path` object.
+      The *path* parameter can now be a :term:`path-like object`.
 
 
 Creating listening connections
@@ -536,7 +536,7 @@ Creating listening connections
 
    .. versionadded:: 3.7
 
-      The *ssl_handshake_timeout* parameter.
+      The *ssl_handshake_timeout* and *start_serving* parameters.
 
    .. versionchanged:: 3.7
 
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 099b59e..8f94ba7 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -18,7 +18,7 @@ Stream functions
    exactly what you want, feel free to copy their code.
 
 
-.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
+.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None)
 
    A wrapper for :meth:`~AbstractEventLoop.create_connection()` returning a (reader,
    writer) pair.
@@ -26,64 +26,102 @@ Stream functions
    The reader returned is a :class:`StreamReader` instance; the writer is
    a :class:`StreamWriter` instance.
 
-   The arguments are all the usual arguments to
-   :meth:`AbstractEventLoop.create_connection` except *protocol_factory*; most
-   common are positional host and port, with various optional keyword arguments
-   following.
+   When specified, the *loop* argument determines which event loop to use,
+   and the *limit* argument determines the buffer size limit used by the
+   returned :class:`StreamReader` instance.
 
-   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 rest of the arguments are passed directly to
+   :meth:`AbstractEventLoop.create_connection`.
 
    This function is a :ref:`coroutine <coroutine>`.
 
-.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
+   .. versionadded:: 3.7
+
+      The *ssl_handshake_timeout* parameter.
+
+.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
 
    Start a socket server, with a callback for each client connected. The return
    value is the same as :meth:`~AbstractEventLoop.create_server()`.
 
-   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.  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
-   converted into a :class:`Task`.
+   The *client_connected_cb* callback is called whenever a new client
+   connection is established.  It receives a reader/writer pair as two
+   arguments, the first is a :class:`StreamReader` instance,
+   and the second is a :class:`StreamWriter` instance.
+
+   *client_connected_cb* accepts a plain callable or a
+   :ref:`coroutine function <coroutine>`; if it is a coroutine function,
+   it will be automatically converted into a :class:`Task`.
 
-   The rest of the arguments are all the usual arguments to
-   :meth:`~AbstractEventLoop.create_server()` except *protocol_factory*; most
-   common are positional *host* and *port*, with various optional keyword
-   arguments following.
+   When specified, the *loop* argument determines which event loop to use,
+   and the *limit* argument determines the buffer size limit used by the
+   :class:`StreamReader` instance passed to *client_connected_cb*.
 
-   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 rest of the arguments are passed directly to
+   :meth:`~AbstractEventLoop.create_server()`.
 
    This function is a :ref:`coroutine <coroutine>`.
 
-.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
+   .. versionadded:: 3.7
+
+      The *ssl_handshake_timeout* and *start_serving* parameters.
+
+.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
 
    A wrapper for :meth:`~AbstractEventLoop.create_unix_connection()` returning
    a (reader, writer) pair.
 
-   See :func:`open_connection` for information about return value and other
-   details.
+   When specified, the *loop* argument determines which event loop to use,
+   and the *limit* argument determines the buffer size limit used by the
+   returned :class:`StreamReader` instance.
+
+   The rest of the arguments are passed directly to
+   :meth:`~AbstractEventLoop.create_unix_connection()`.
 
    This function is a :ref:`coroutine <coroutine>`.
 
    Availability: UNIX.
 
-.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
+   .. versionadded:: 3.7
+
+      The *ssl_handshake_timeout* parameter.
+
+   .. versionchanged:: 3.7
+
+      The *path* parameter can now be a :term:`path-like object`
+
+.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
 
    Start a UNIX Domain Socket server, with a callback for each client connected.
 
-   See :func:`start_server` for information about return value and other
-   details.
+   The *client_connected_cb* callback is called whenever a new client
+   connection is established.  It receives a reader/writer pair as two
+   arguments, the first is a :class:`StreamReader` instance,
+   and the second is a :class:`StreamWriter` instance.
+
+   *client_connected_cb* accepts a plain callable or a
+   :ref:`coroutine function <coroutine>`; if it is a coroutine function,
+   it will be automatically converted into a :class:`Task`.
+
+   When specified, the *loop* argument determines which event loop to use,
+   and the *limit* argument determines the buffer size limit used by the
+   :class:`StreamReader` instance passed to *client_connected_cb*.
+
+   The rest of the arguments are passed directly to
+   :meth:`~AbstractEventLoop.create_unix_server()`.
 
    This function is a :ref:`coroutine <coroutine>`.
 
    Availability: UNIX.
 
+   .. versionadded:: 3.7
+
+      The *ssl_handshake_timeout* and *start_serving* parameters.
+
+   .. versionchanged:: 3.7
+
+      The *path* parameter can now be a :term:`path-like object`.
+
 
 StreamReader
 ============
@@ -475,4 +513,3 @@ Coroutine waiting until a socket receives data using the
    <asyncio-watch-read-event>` example uses the low-level
    :meth:`AbstractEventLoop.add_reader` method to register the file descriptor of a
    socket.
-
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 9a6f542..8a3afdf 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -699,11 +699,12 @@ include:
   gained support for Unix sockets.
   (Contributed by Quentin Dawans in :issue:`31245`.)
 
-* The :meth:`loop.create_connection() <asyncio.AbstractEventLoop.create_connection>`,
+* The :func:`asyncio.open_connection`, :func:`asyncio.start_server` functions,
+  :meth:`loop.create_connection() <asyncio.AbstractEventLoop.create_connection>`,
   :meth:`loop.create_server() <asyncio.AbstractEventLoop.create_server>`,
-  :meth:`loop.create_unix_server() <asyncio.AbstractEventLoop.create_unix_server>`, and
   :meth:`loop.create_accepted_socket() <asyncio.BaseEventLoop.connect_accepted_socket>`
-  now accept the *ssl_handshake_timeout* keyword argument.
+  methods and their corresponding UNIX socket variants now accept the
+  *ssl_handshake_timeout* keyword argument.
   (Contributed by Neil Aspinall in :issue:`29970`.)
 
 * The new :meth:`Handle.cancelled() <asyncio.Handle.cancelled>` method returns