Document roommanager

src/roommanager.h

@@ -20,17 +20,34 @@ class User;
 
 using namespace Quotient;
 
+/**
+ * @class RoomManager
+ *
+ * A singleton class to help manage which room is open in NeoChat.
+ */
 class RoomManager : public QObject, public UriResolverBase
 {
     Q_OBJECT
 
-    /// This property holds the current open room in the NeoChat, if any.
+    /**
-    /// \sa hasOpenRoom
+     * @brief The current open room in NeoChat, if any.
+     *
+     * @sa hasOpenRoom
+     */
     Q_PROPERTY(NeoChatRoom *currentRoom READ currentRoom NOTIFY currentRoomChanged)
 
-    /// This property holds whether a room is currently open in NeoChat.
+    /**
-    /// \sa room
+     * @brief Whether a room is currently open in NeoChat.
+     *
+     * @sa room
+     */
     Q_PROPERTY(bool hasOpenRoom READ hasOpenRoom NOTIFY currentRoomChanged)
+
+    /**
+     * @brief The ChatDocumentHandler for the open room.
+     *
+     * @sa ChatDocumentHandler
+     */
     Q_PROPERTY(ChatDocumentHandler *chatDocumentHandler READ chatDocumentHandler WRITE setChatDocumentHandler NOTIFY chatDocumentHandlerChanged)
 
 public:
@@ -38,71 +55,173 @@ public:
     virtual ~RoomManager();
     static RoomManager &instance();
 
-    /// Load the last opened room or the welcome page.
-    Q_INVOKABLE void loadInitialRoom();
-
-    /// This method will tell the NeoChat to open the message list
-    /// with the given room.
-    Q_INVOKABLE void enterRoom(NeoChatRoom *room);
-
-    Q_INVOKABLE void openWindow(NeoChatRoom *room);
-
-    /// Leave the room and close it if it is open.
-    Q_INVOKABLE void leaveRoom(NeoChatRoom *room);
-
-    /// Getter for the currentRoom property.
     NeoChatRoom *currentRoom() const;
 
-    /// Getter for the hasOpenRoom property.
     bool hasOpenRoom() const;
 
+    /**
+     * @brief Load the last opened room or the welcome page.
+     */
+    Q_INVOKABLE void loadInitialRoom();
+
+    /**
+     * @brief Enter the given room.
+     *
+     * This method will tell NeoChat to open the message list with the given room.
+     */
+    Q_INVOKABLE void enterRoom(NeoChatRoom *room);
+
+    /**
+     * @brief Open a new window with the given room.
+     *
+     * The open window will have its own message list for the given room.
+     */
+    Q_INVOKABLE void openWindow(NeoChatRoom *room);
+
+    /**
+     * @brief Leave the room and close it if it is open.
+     */
+    Q_INVOKABLE void leaveRoom(NeoChatRoom *room);
+
     // Overrided methods from UriResolverBase
+    /**
+     * @brief Resolve a user URI.
+     *
+     * This overloads Quotient::UriResolverBase::visitUser().
+     *
+     * Called by Quotient::UriResolverBase::visitResource() when the passed URI
+     * identifies a Matrix user.
+     *
+     * @sa Quotient::UriResolverBase::visitUser(), Quotient::UriResolverBase::visitResource()
+     */
     UriResolveResult visitUser(User *user, const QString &action) override;
-    void joinRoom(Quotient::Connection *account, const QString &roomAliasOrId, const QStringList &viaServers) override;
+
-    // TODO: it need also override in the feature?
+    /**
-#ifdef QUOTIENT_07
+     * @brief Visit a room.
-    void knockRoom(Quotient::Connection *account, const QString &roomAliasOrId, const QString &reason, const QStringList &viaServers);
+     *
-#endif
+     * This overloads Quotient::UriResolverBase::visitRoom().
+     *
+     * Called by Quotient::UriResolverBase::visitResource() when the passed URI
+     * identifies a room or an event in a room.
+     *
+     * @sa Quotient::UriResolverBase::visitRoom(), Quotient::UriResolverBase::visitResource()
+     */
     Q_INVOKABLE void visitRoom(Quotient::Room *room, const QString &eventId) override;
+
+    /**
+     * @brief Join a room.
+     *
+     * This overloads Quotient::UriResolverBase::joinRoom().
+     *
+     * Called by Quotient::UriResolverBase::visitResource() when the passed URI has
+     * `action() == "join"` and identifies a room that the user defined by the
+     * Connection argument is not a member of.
+     *
+     * @sa Quotient::UriResolverBase::joinRoom(), Quotient::UriResolverBase::visitResource()
+     */
+    void joinRoom(Quotient::Connection *account, const QString &roomAliasOrId, const QStringList &viaServers) override;
+
+    /**
+     * @brief Visit a non-matrix resource.
+     *
+     * This overloads Quotient::UriResolverBase::visitNonMatrix().
+     *
+     * Called by Quotient::UriResolverBase::visitResource() when the passed URI
+     * has `type() == NonMatrix`
+     *
+     * @sa Quotient::UriResolverBase::visitNonMatrix(), Quotient::UriResolverBase::visitResource()
+     */
     Q_INVOKABLE bool visitNonMatrix(const QUrl &url) override;
 
+    // TODO: it need also override in the feature?
+#ifdef QUOTIENT_07
+    /**
+     * @brief Knock a room.
+     *
+     * See https://spec.matrix.org/latest/client-server-api/#knocking-on-rooms for
+     * knocking on rooms.
+     */
+    void knockRoom(Quotient::Connection *account, const QString &roomAliasOrId, const QString &reason, const QStringList &viaServers);
+#endif
+
+    /**
+     * @brief Open the given resource.
+     *
+     * Convenience function to call Quotient::UriResolverBase::visitResource() from
+     * QML if valid.
+     *
+     * @sa Quotient::UriResolverBase::visitResource()
+     */
     Q_INVOKABLE void openResource(const QString &idOrUri, const QString &action = {});
 
-    /// Call this when the current used connection is dropped.
+    /**
+     * @brief Call this when the current used connection is dropped.
+     */
     Q_INVOKABLE void reset();
 
     ChatDocumentHandler *chatDocumentHandler() const;
     void setChatDocumentHandler(ChatDocumentHandler *handler);
 
+    /**
+     * @brief Set a URL to be loaded as the initial room.
+     */
     void setUrlArgument(const QString &arg);
 
 Q_SIGNALS:
-    /// Signal triggered when the current open room change.
     void currentRoomChanged();
 
-    /// Signal triggered when the pageStack should push a new page with the
+    /**
-    /// message list for the given room.
+     * @brief Push a new room page.
+     *
+     * Signal triggered when the main window pageStack should push a new page with
+     * the message list for the given room.
+     *
+     * @param room the room to be shown on the new page.
+     * @param event the event to got to if available.
+     */
     void pushRoom(NeoChatRoom *room, const QString &event);
 
-    /// Signal triggered when the room displayed by the message list should
+    /**
-    /// be changed.
+     * @brief Replace the existing room.
+     *
+     * Signal triggered when the room displayed by the message list should be changed.
+     *
+     * @param room the room to be shown on the new page.
+     * @param event the event to got to if available.
+     */
     void replaceRoom(NeoChatRoom *room, const QString &event);
 
-    /// Go to the specified event in the current room.
+    /**
+     * @brief Go to the specified event in the current room.
+     */
     void goToEvent(const QString &event);
 
-    /// Signal triggered when a room need to be opened in a new window.
+    /**
+     * @brief Open room in a new window.
+     *
+     * Signal triggered when a room needs to be opened in a new window.
+     */
     void openRoomInNewWindow(NeoChatRoom *room);
 
-    /// Ask current room to open the user's details for the give user.
+    /**
-    /// This can assume the user is loaded.
+     * @brief Show details for the given user.
+     *
+     * Ask current room to open the user's details for the give user.
+     * This assumes the user is loaded.
+     */
     void showUserDetail(const Quotient::User *user);
 
-    /// Ask current room to show confirmation dialog to open direct chat.
+    /**
-    /// This can assume the user is loaded.
+     * @brief Show the direct chat confirmation dialog.
+     *
+     * Ask current room to show confirmation dialog to open direct chat.
+     * This assumes the user is loaded.
+     */
     void askDirectChatConfirmation(const Quotient::User *user);
 
-    /// Displays warning to the user.
+    /**
+     * @brief Displays warning to the user.
+     */
     void warning(const QString &title, const QString &message);
 
     void chatDocumentHandlerChanged();