Update docs about multi socket support

3 files changed, 49 insertions, 19 deletions

diff --git a/docs/api.rst b/docs/api.rst
index c85d4e1..5e0a523 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -5,6 +5,6 @@
 
 .. module:: waitress
 
-.. function:: serve(app, host='0.0.0.0', port=8080, unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1204, recv_bytes=8192, send_bytes=18000, outbuf_overflow=104856, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)
+.. function:: serve(app, listen='0.0.0.0:8080', unix_socket=None, unix_socket_perms='600', threads=4, url_scheme='http', url_prefix='', ident='waitress', backlog=1204, recv_bytes=8192, send_bytes=18000, outbuf_overflow=104856, inbuf_overflow=52488, connection_limit=1000, cleanup_interval=30, channel_timeout=120, log_socket_errors=True, max_request_header_size=262144, max_request_body_size=1073741824, expose_tracebacks=False)
 
      See :ref:`arguments` for more information.
diff --git a/docs/arguments.rst b/docs/arguments.rst
index cc74c0c..bc67da4 100644
--- a/docs/arguments.rst
+++ b/docs/arguments.rst
@@ -10,9 +10,49 @@ host
     hostname or IP address (string) on which to listen, default ``0.0.0.0``,
     which means "all IP addresses on this host".
 
+    .. warning::
+        May not be used with ``listen``
+
+    .. deprecated:: 1.0
+
 port
     TCP port (integer) on which to listen, default ``8080``
 
+    .. warning::
+        May not be used with ``listen``
+
+    .. deprecated:: 1.0
+
+listen
+    Tell waitress to listen on an host/port combination. When provided on the
+    command line, one can pass the argument multiple times:
+
+    Example:
+
+        - ``--listen=127.0.0.1:8080``
+        - ``--listen=[::1]:8080``
+        - ``--listen=*:8080``
+
+    When used from an application, it has to be provided as a space delineated list of host/port:
+
+    Example:
+
+        - ``listen="127.0.0.1:8080 [::1]:8080"``
+        - ``listen="*:8080 *:6543"``
+
+	A wildcard for the hostname is also supported and will bind to both
+	IPv4/IPv6 depending on whether they are enabled or disabled.
+
+	IPv6 IP addresses are supported by surrounding the IP address with brackets.
+
+    .. versionadded:: 1.0
+
+ipv4
+    Enable or disable IPv4 (boolean)
+
+ipv6
+    Enable or disable IPv6 (boolean)
+
 unix_socket
     Path of Unix socket (string), default is ``None``. If a socket path is
     specified, a Unix domain socket is made instead of the usual inet domain
diff --git a/docs/index.rst b/docs/index.rst
index 6a595ad..8963aa8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -15,17 +15,11 @@ Here's normal usage of the server:
 .. code-block:: python
 
    from waitress import serve
-   serve(wsgiapp, host='0.0.0.0', port=8080)
+   serve(wsgiapp, listen='*:8080')
 
-If you want to serve your application on all IP addresses, on port 8080, you
-can omit the ``host`` and ``port`` arguments and just call ``serve`` with the
-WSGI app as a single argument:
+This will run waitress on port 8080 on all available IP addresses, both IPv4
+and IPv6.
 
-.. code-block:: python
-
-   from waitress import serve
-   serve(wsgiapp)
-   
 Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.
 
 If you want to serve your application through a UNIX domain socket (to serve
@@ -49,8 +43,7 @@ lets you use Waitress's WSGI gateway from a configuration file, e.g.:
 
   [server:main]
   use = egg:waitress#main
-  host = 127.0.0.1
-  port = 8080
+  listen = 127.0.0.1:8080
 
 The :term:`PasteDeploy` syntax for UNIX domain sockets is analagous:
 
@@ -67,7 +60,7 @@ Additionally, there is a command line runner called ``waitress-serve``, which
 can be used in development and in situations where the likes of
 :term:`PasteDeploy` is not necessary::
 
-    waitress-serve --port=8041 myapp:wsgifunc
+    waitress-serve --listen=*:8041 myapp:wsgifunc
 
 For more information on this, see :ref:`runner`.
 
@@ -153,7 +146,7 @@ You can have the Waitress server use the ``https`` url scheme by default.:
 .. code-block:: python
 
    from waitress import serve
-   serve(wsgiapp, host='0.0.0.0', port=8080, url_scheme='https')
+   serve(wsgiapp, listen='0.0.0.0:8080', url_scheme='https')
 
 This works if all URLs generated by your application should use the ``https``
 scheme.
@@ -188,7 +181,7 @@ account.:
 .. code-block:: python
 
    from waitress import serve
-   serve(wsgiapp, host='0.0.0.0', port=8080, url_prefix='/foo')
+   serve(wsgiapp, listen='0.0.0.0:8080', url_prefix='/foo')
 
 Setting this to any value except the empty string will cause the WSGI
 ``SCRIPT_NAME`` value to be that value, minus any trailing slashes you add, and
@@ -257,8 +250,7 @@ PasteDeploy-style configuration:
 
    [server:main]
    use = egg:waitress#main
-   host = 127.0.0.1
-   port = 8080
+   listen = 127.0.0.1:8080
 
 Note that you can also set ``PATH_INFO`` and ``SCRIPT_NAME`` using
 PrefixMiddleware too (its original purpose, really) instead of using Waitress'
@@ -287,8 +279,6 @@ Change History
 Known Issues
 ------------
 
-- Does not yet support IPv6 natively.
-
 - Does not support SSL natively.
 
 Support and Development