Brush up SsoSession; document Connection::prepareForSso

Although parented to Connection, SsoSession was pretty leaky in that
unsuccessful login attempts didn't delete the object and in some errors
didn't even close the local HTTP socket (though new connections would no
more be accepted). Also, without the documentation it wasn't clear who
owns the object returned by Connection::prepareForSso(). Now it is.

Unfortunately, it's not easy to cover SsoSession with tests. Basically,
it takes a homeserver and a mock "SSO agent" that would check
the SSO URL for validity and then both send the login authorisation
to the homeserver as well as ping the callback given by SsoSession.
Maybe for another time.

1 files changed, 11 insertions, 0 deletions

diff --git a/lib/connection.h b/lib/connection.h
index b4476347..28688cc1 100644
--- a/lib/connection.h
+++ b/lib/connection.h
@@ -443,6 +443,17 @@ public:
                                     std::forward<JobArgTs>(jobArgs)...);
     }
 
+    //! \brief Start a local HTTP server and generate a single sign-on URL
+    //!
+    //! This call does the preparatory steps to carry out single sign-on
+    //! sequence
+    //! \sa https://matrix.org/docs/guides/sso-for-client-developers
+    //! \return A proxy object holding two URLs: one for SSO on the chosen
+    //!         homeserver and another for the local callback address. Normally
+    //!         you won't need the callback URL unless you proxy the response
+    //!         with a custom UI. You do not need to delete the SsoSession
+    //!         object; the Connection that issued it will dispose of it once
+    //!         the login sequence completes (with any outcome).
     Q_INVOKABLE SsoSession* prepareForSso(const QString& initialDeviceName,
                                           const QString& deviceId = {});