The arguments @var{host} and @var{service} specify where to connect to;
@var{host} is the host name (a string), and @var{service} is the name of
-a defined network service (a string) or a port number (an integer).
+a defined network service (a string) or a port number (an integer like
+@code{80} or an integer string like @code{"80"}).
The remaining arguments @var{parameters} are keyword/argument pairs
that are mainly relevant to encrypted connections:
@item :service @var{service}
@var{service} specifies a port number to connect to; or, for a server,
-the port number to listen on. It should be a service name that
-translates to a port number, or an integer specifying the port number
+the port number to listen on. It should be a service name like
+@samp{"http"} that translates to a port number, or an integer like @samp{80}
+or an integer string like @samp{"80"} that specifies the port number
directly. For a server, it can also be @code{t}, which means to let
the system select an unused port number.
ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6,
respectively.
+@item :use-external-socket @var{use-external-socket}
+If @var{use-external-socket} is non-@code{nil} use any sockets passed
+to Emacs on invocation instead of allocating one. This is used by the
+Emacs server code to allow on-demand socket activation. If Emacs
+wasn't passed a socket, this option is silently ignored.
+
@item :local @var{local-address}
For a server process, @var{local-address} is the address to listen on.
It overrides @var{family}, @var{host} and @var{service}, so you
succeeds or fails, Emacs will call the sentinel function, with a
second argument matching @code{"open"} (if successful) or
@code{"failed"}. The default is to block, so that
-@code{make-network-process} does not return until the connection
-has succeeded or failed.
+@code{make-network-process} does not return until the connection has
+succeeded or failed.
+
+If you're setting up an asynchronous TLS connection, you have to also
+provide the @code{:tls-parameters} parameter (see below).
+
+Depending on the capabilities of Emacs, how asynchronous
+@code{:nowait} is may vary. The three elements that may (or may not)
+be done asynchronously are domain name resolution, socket setup, and
+(for TLS connections) TLS negotiation.
+
+Many functions that interact with process objects, (for instance,
+@code{process-datagram-address}) rely on them at least having a socket
+before they can return a useful value. These functions will block
+until the socket has achieved the desired status. The recommended way
+of interacting with asynchronous sockets is to place a sentinel on the
+process, and not try to interact with it before it has changed status
+to @samp{"run"}. That way, none of these functions will block.
+
+@item :tls-parameters
+When opening a TLS connection, this should be where the first element
+is the TLS type (which should either be @code{gnutls-x509pki} or
+@code{gnutls-anon}, and the remaining elements should form a keyword
+list acceptable for @code{gnutls-boot}. (This keyword list can be
+obtained from the @code{gnutls-boot-parameters} function.) The TLS
+connection will then be negotiated after completing the connection to
+the host.
@item :stop @var{stopped}
If @var{stopped} is non-@code{nil}, start the network connection or