From b7de9c00b79ef0d187190aa5d126bff7503f471f Mon Sep 17 00:00:00 2001 From: Alexey Rusakov Date: Wed, 13 Oct 2021 19:55:40 +0200 Subject: connection.h: more doc-comments --- lib/connection.h | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) (limited to 'lib/connection.h') diff --git a/lib/connection.h b/lib/connection.h index 1a6ca9b0..05a3bb7f 100644 --- a/lib/connection.h +++ b/lib/connection.h @@ -479,10 +479,23 @@ public: } public Q_SLOTS: - /** Set the homeserver base URL */ + /// \brief Set the homeserver base URL and retrieve its login flows + /// + /// \sa LoginFlowsJob, loginFlows, loginFlowsChanged, homeserverChanged void setHomeserver(const QUrl& baseUrl); - /** Determine and set the homeserver from MXID */ + /// \brief Determine and set the homeserver from MXID + /// + /// This attempts to resolve the homeserver by requesting + /// .well-known/matrix/client record from the server taken from the MXID + /// serverpart. If there is no record found, the serverpart itself is + /// attempted as the homeserver base URL; if the record is there but + /// is malformed (e.g., the homeserver base URL cannot be found in it) + /// resolveError() is emitted and further processing stops. Otherwise, + /// setHomeserver is called, preparing the Connection object for the login + /// attempt. + /// \param mxid user Matrix ID, such as @someone:example.org + /// \sa setHomeserver, homeserverChanged, loginFlowsChanged, resolveError void resolveServer(const QString& mxid); /** \brief Log in using a username and password pair @@ -638,6 +651,11 @@ public Q_SLOTS: virtual LeaveRoomJob* leaveRoom(Room* room); Q_SIGNALS: + /// \brief Initial server resolution has failed + /// + /// This signal is emitted when resolveServer() did not manage to resolve + /// the homeserver using its .well-known/client record or otherwise. + /// \sa resolveServer void resolveError(QString error); void homeserverChanged(QUrl baseUrl); -- cgit v1.2.3