Document how to wait for clients to disconnect.

Fix #1756.

Author: aaugustin

src/websockets/asyncio/server.py

@@ -552,16 +552,31 @@ async def handler(websocket):
             await stop.wait()
 
     Alternatively, await it and call :meth:`~Server.serve_forever` to serve
-    requests, then cancel it or call :meth:`~Server.close` to stop the server::
+    requests, then cancel it to stop the server::
 
         server = await serve(handler, host, port)
         await server.serve_forever()
 
-    The following pattern is functional but redundant: by the time the context
+    Combining these two patterns works, but is unnecessary: when the context
     manager exits, :meth:`~Server.serve_forever` has already closed the server::
 
-        async with serve(handler, host, port) as server:
-            await server.serve_forever()
+        async with serve(handler, host, port) as server:  # don't do this!
+            await server.serve_forever()                  # it's redundant
+
+    You can also stop the server gracefully by calling its
+    :meth:`~Server.close` method::
+
+        server = await serve(handler, host, port)
+        try:
+            await stop.wait()
+        finally:
+            server.close()
+            await server.wait_closed()
+
+    By default, closing the server closes connections with code 1001 (going
+    away). You can keep connections alive and wait for clients to disconnect::
+
+        server.close(close_connections=False)
 
     Args:
         handler: Connection handler. It receives the WebSocket connection,

src/websockets/sync/server.py

@@ -544,8 +544,15 @@ def handler(websocket):
         with serve(handler, ...) as server:
             server.serve_forever()
 
-    To stop the server gracefully, call its :meth:`~Server.shutdown` method from
-    another thread.
+    You can stop the server gracefully by calling its :meth:`~Server.shutdown`
+    method from another thread::
+
+        server.shutdown()
+
+    By default, closing the server closes connections with code 1001 (going
+    away). You can keep connections alive and wait for clients to disconnect::
+
+        server.shutdown(close_connections=False)
 
     Args:
         handler: Connection handler. It receives the WebSocket connection,

src/websockets/trio/server.py

@@ -439,7 +439,7 @@ async def handler(websocket):
             async with server:
                 await stop.wait()
 
-    Alternatively, to stop the server gracefully, call its
+    Alternatively, you can stop the server gracefully by calling its
     :meth:`~Server.aclose` method::
 
         with trio.open_nursery() as nursery:
@@ -449,6 +449,11 @@ async def handler(websocket):
             finally:
                 await server.aclose()
 
+    By default, closing the server closes connections with code 1001 (going
+    away). You can keep connections alive and wait for clients to disconnect::
+
+        await server.aclose(close_connections=False)
+
     Args:
         handler: Connection handler. It receives the WebSocket connection,
             which is a :class:`ServerConnection`, in argument.