httpserver: Update docs

diff --git a/docs/httpserver.rst b/docs/httpserver.rst
index 88c74376bdd0704ee7d9d7b0c028cd53a1c9a5a5..ddb7766793b1fc81e7c44f0f76dd5f76ed9e2212 100644 (file)
--- a/docs/httpserver.rst
+++ b/docs/httpserver.rst
@@ -5,5 +5,8 @@
 
    HTTP Server
    -----------
-   .. autoclass:: HTTPServer
+   .. autoclass:: HTTPServer(request_callback: Union[httputil.HTTPServerConnectionDelegate, Callable[[httputil.HTTPServerRequest], None]], no_keep_alive: bool = False, xheaders: bool = False, ssl_options: Union[Dict[str, Any], ssl.SSLContext] = None, protocol: str = None, decompress_request: bool = False, chunk_size: int = None, max_header_size: int = None, idle_connection_timeout: float = None, body_timeout: float = None, max_body_size: int = None, max_buffer_size: int = None, trusted_downstream: List[str] = None)
       :members:
+
+      The public interface of this class is mostly inherited from
+      `.TCPServer` and is documented under that class.

diff --git a/tornado/httpserver.py b/tornado/httpserver.py
index 9376c568594ebfbc6763043c23e372342dd14a92..8044a4f828ec78c0f55aa746ab68a0389f2569fc 100644 (file)
--- a/tornado/httpserver.py
+++ b/tornado/httpserver.py
@@ -168,6 +168,10 @@ class HTTPServer(TCPServer, Configurable, httputil.HTTPServerConnectionDelegate)
         max_buffer_size: int = None,
         trusted_downstream: List[str] = None,
     ) -> None:
+        # This method's signature is not extracted with autodoc
+        # because we want its arguments to appear on the class
+        # constructor. When changing this signature, also update the
+        # copy in httpserver.rst.
         self.request_callback = request_callback
         self.xheaders = xheaders
         self.protocol = protocol
@@ -198,6 +202,19 @@ class HTTPServer(TCPServer, Configurable, httputil.HTTPServerConnectionDelegate)
         return HTTPServer
 
     async def close_all_connections(self) -> None:
+        """Close all open connections and asynchronously wait for them to finish.
+
+        This method is used in combination with `~.TCPServer.stop` to
+        support clean shutdowns (especially for unittests). Typical
+        usage would call ``stop()`` first to stop accepting new
+        connections, then ``await close_all_connections()`` to wait for
+        existing connections to finish.
+
+        This method does not currently close open websocket connections.
+
+        Note that this method is a coroutine and must be caled with ``await``.
+
+        """
         while self._connections:
             # Peek at an arbitrary element of the set
             conn = next(iter(self._connections))