gh-100920: Update documentation for `asyncio.StreamWriter.wait_closed` (GH-101514)

(cherry picked from commit 5c39daf50b7f388f9b24bb2d6ef415955440bebf)

Co-authored-by: Viet Than <thanhoangviet@gmail.com>

diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index bed10a40fb7e6b041e14a9e15d7be01afb648c26..f0fcac1a793737c1a3e921ebcecfa7f6e3652cba 100644 (file)
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -281,7 +281,8 @@ StreamWriter
 
       The method closes the stream and the underlying socket.
 
-      The method should be used along with the ``wait_closed()`` method::
+      The method should be used, though not mandatory,
+      along with the ``wait_closed()`` method::
 
          stream.close()
          await stream.wait_closed()
@@ -332,7 +333,8 @@ StreamWriter
       Wait until the stream is closed.
 
       Should be called after :meth:`close` to wait until the underlying
-      connection is closed.
+      connection is closed, ensuring that all data has been flushed
+      before e.g. exiting the program.
 
       .. versionadded:: 3.7
 
@@ -361,6 +363,7 @@ TCP echo client using the :func:`asyncio.open_connection` function::
 
         print('Close the connection')
         writer.close()
+        await writer.wait_closed()
 
     asyncio.run(tcp_echo_client('Hello World!'))
 
@@ -393,6 +396,7 @@ TCP echo server using the :func:`asyncio.start_server` function::
 
         print("Close the connection")
         writer.close()
+        await writer.wait_closed()
 
     async def main():
         server = await asyncio.start_server(
@@ -449,6 +453,7 @@ Simple example querying HTTP headers of the URL passed on the command line::
 
         # Ignore the body, close the socket
         writer.close()
+        await writer.wait_closed()
 
     url = sys.argv[1]
     asyncio.run(print_http_headers(url))
@@ -494,6 +499,7 @@ Coroutine waiting until a socket receives data using the
         # Got data, we are done: close the socket
         print("Received:", data.decode())
         writer.close()
+        await writer.wait_closed()
 
         # Close the second socket
         wsock.close()