* proto-stream.el (open-protocol-stream): Document the return value.

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 600b442..05d3114 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,7 @@
+2011-02-06  Lars Ingebrigtsen  <larsi@gnus.org>
+
+       * proto-stream.el (open-protocol-stream): Document the return value.
+

 2011-02-06  Julien Danjou  <julien@danjou.info>
 
        * message.el (message-setup-1): Handle message-generate-headers-first
 2011-02-06  Julien Danjou  <julien@danjou.info>
 
        * message.el (message-setup-1): Handle message-generate-headers-first

diff --git a/lisp/proto-stream.el b/lisp/proto-stream.el
index 9117ac9..fdf2abf 100644 (file)
--- a/lisp/proto-stream.el
+++ b/lisp/proto-stream.el
@@ -94,7 +94,15 @@ query server for capabilities.  For instance, for IMAP this is
 :starttls-function -- a function that takes one parameter, which
 is the response to the capaibility command.  It should return nil
 if it turns out that the server doesn't support STARTTLS, or the
 :starttls-function -- a function that takes one parameter, which
 is the response to the capaibility command.  It should return nil
 if it turns out that the server doesn't support STARTTLS, or the

-command to switch on STARTTLS otherwise."
+command to switch on STARTTLS otherwise.
+
+The return value from this function is a four-element list, where
+the first element is the stream (if connection was successful);
+the second element is the \"greeting\", i. e., the string the
+server sent over on initial contact; the third element is the
+capability string; and the fourth element is either `network' or
+`tls', depending on whether the connection ended up being
+encrypted or not."

   (let ((type (or (cadr (memq :type parameters)) 'network)))
     (cond
      ((eq type 'starttls)
   (let ((type (or (cadr (memq :type parameters)) 'network)))
     (cond
      ((eq type 'starttls)