From: Robert Pluim <rpluim@gmail.com>
Date: Tue, 5 Nov 2024 12:51:21 +0000 (+0100)
Subject: Improve 'open-network-stream' documentation.
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=cc17d3ecd4536d51bc02960b7f7226211452b797;p=emacs.git

Improve 'open-network-stream' documentation.

* doc/lispref/processes.texi (Network): Correct explanation of
':warn-unless-encrypted'.  Document ':error' return keyword.
* lisp/net/network-stream.el (open-network-stream): Improve
':return-list' documentation.  Document ':error'.  Correct
explanation of ':warn-unless-encrypted'.

(cherry picked from commit 3231af3727b450404efd6f49ddf5c95c5a8cbb0f)
---

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index bad0f7534e1..eaa465ce7b8 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -2684,10 +2684,12 @@ If non-@code{nil}, do opportunistic @acronym{STARTTLS} upgrades even if Emacs
 doesn't have built-in @acronym{TLS} support.
 
 @item :warn-unless-encrypted @var{boolean}
-If non-@code{nil}, and @code{:return-value} is also non-@code{nil},
-Emacs will warn if the connection isn't encrypted.  This is useful for
-protocols like @acronym{IMAP} and the like, where most users would
-expect the network traffic to be encrypted.
+If non-@code{nil}, warn the user if the final connection type is not
+encrypted.  This is useful for protocols like @acronym{IMAP} and the
+like, where most users would expect the network traffic to be encrypted.
+This may be due to @acronym{STARTTLS} upgrade failure, specifying
+@code{:return-list} non-@code{nil} allows you to capture any error
+encountered.
 
 @vindex network-stream-use-client-certificates
 @item :client-certificate @var{list-or-t}
@@ -2713,6 +2715,9 @@ If non-@code{nil}, the greeting string returned by the host.
 If non-@code{nil}, the host's capability string.
 @item :type @var{symbol}
 The connection type: @samp{plain} or @samp{tls}.
+@item :error @var{symbol}
+A string describing any error encountered when perfoming
+@acronym{STARTTLS} upgrade.
 @end table
 
 @item :shell-command @var{string-or-nil}
diff --git a/lisp/net/network-stream.el b/lisp/net/network-stream.el
index dcb3ad61f6d..89d3e4f19c1 100644
--- a/lisp/net/network-stream.el
+++ b/lisp/net/network-stream.el
@@ -117,15 +117,18 @@ values:
 used to decode and encode the data which the process reads and
 writes.  See `make-network-process' for details.
 
-:return-list specifies this function's return value.
-  If omitted or nil, return a process object.  A non-nil means to
-  return (PROC . PROPS), where PROC is a process object and PROPS
-  is a plist of connection properties, with these keywords:
+:return-list controls the form of the function's return value.
+  If omitted or nil, return a process object.  Anything else means to
+  return (PROC . PROPS), where PROC is a process object, and PROPS is a
+  plist of connection properties, which may include the following
+  keywords:
    :greeting -- the greeting returned by HOST (a string), or nil.
    :capabilities -- a string representing HOST's capabilities,
                     or nil if none could be found.
    :type -- the resulting connection type; `plain' (unencrypted)
             or `tls' (TLS-encrypted).
+   :error -- A string describing any error when attempting
+             to negotiate STARTTLS.
 
 :end-of-command specifies a regexp matching the end of a command.
 
@@ -164,8 +167,9 @@ writes.  See `make-network-process' for details.
 :use-starttls-if-possible is a boolean that says to do opportunistic
 STARTTLS upgrades even if Emacs doesn't have built-in TLS functionality.
 
-:warn-unless-encrypted is a boolean which, if :return-list is
-non-nil, is used warn the user if the connection isn't encrypted.
+:warn-unless-encrypted, if non-nil, warn the user if the connection
+isn't encrypted (i.e. STARTTLS failed).  Additionally, setting
+:return-list non-nil allows capturing any error response.
 
 :nogreeting is a boolean that can be used to inhibit waiting for
 a greeting from the server.