From 3231af3727b450404efd6f49ddf5c95c5a8cbb0f Mon Sep 17 00:00:00 2001
From: Robert Pluim <rpluim@gmail.com>
Date: Tue, 5 Nov 2024 13:51:21 +0100
Subject: [PATCH] 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'.
---
 doc/lispref/processes.texi | 13 +++++++++----
 lisp/net/network-stream.el | 16 ++++++++++------
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index 53468e0d252..2c19275f946 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -2686,10 +2686,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}
@@ -2715,6 +2717,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.