docs(stream): improve doc of negotiate

1 files changed, 6 insertions, 2 deletions

diff --git a/lib/stream.ml b/lib/stream.ml
index 2c6bf37..e6a46b8 100644
--- a/lib/stream.ml
+++ b/lib/stream.ml
@@ -35,12 +35,16 @@ let parse_features (el : Xml.element) : features =
        {mechanisms=[]; starttls=`None; unknown=[]}
        (List.filter_map find_left el.children)
 
-(** [negotiate domain stream] is a promise containing the features supported by the
-    XMPP server communicating with [stream].
+(** [negotiate domain portal auth] is a promise containing the features supported by the
+    XMPP server [portal], after eventual STARTTLS negotiation and authentication using
+    the auth config [auth].
 
     This function should be called every time a stream needs to be reopened and stream
     negotiation takes place.
 
+    When the XMPP server advertises optional STARTTLS support, whether the connection
+    will be upgraded to STARTTLS depends on [prefer_starttls].
+
     Basically, it conforms to
     {{: https://datatracker.ietf.org/doc/html/rfc6120#section-4.3 }}. *)
 let negotiate