Finish documenting AOClient

include/aoclient.h

@@ -185,7 +185,7 @@ class AOClient : public QObject {
     ClientVersion version;
 
     /**
-      * @brief The authorisation bitflag, representing what privileges a client can have.
+      * @brief The authorisation bitflag, representing what permissions a client can have.
       */
     QMap<QString, unsigned long long> ACLFlags {
         {"KICK",            1ULL << 0},
@@ -332,12 +332,12 @@ class AOClient : public QObject {
     void sendServerBroadcast(QString message);
 
     /**
-     * @brief Checks if the client would be authorised to something based on its necessary privileges.
+     * @brief Checks if the client would be authorised to something based on its necessary permissions.
      *
-     * @param acl_mask The privileges bitflag that the client's own privileges should be checked against.
+     * @param acl_mask The permissions bitflag that the client's own permissions should be checked against.
      *
-     * @return True if the client's privileges are high enough for `acl_mask`, or higher than it.
+     * @return True if the client's permissions are high enough for `acl_mask`, or higher than it.
-     * False if the client is missing some privileges.
+     * False if the client is missing some permissions.
      */
     bool checkAuth(unsigned long long acl_mask);
 
@@ -543,7 +543,7 @@ class AOClient : public QObject {
 
     /// Describes a packet's interpretation details.
     struct PacketInfo {
-        unsigned long long acl_mask; //!< The privileges necessary for the packet.
+        unsigned long long acl_mask; //!< The permissions necessary for the packet.
         int minArgs; //!< The minimum arguments needed for the packet to be interpreted correctly / make sense.
         void (AOClient::*action)(AreaData*, int, QStringList, AOPacket);
     };
@@ -600,7 +600,7 @@ class AOClient : public QObject {
     void cmdDefault(int argc, QStringList argv);
 
     /**
-     * @brief Lists all the commands that the caller client has the privileges to use.
+     * @brief Lists all the commands that the caller client has the permissions to use.
      *
      * @details No arguments.
      *
@@ -613,14 +613,91 @@ class AOClient : public QObject {
       */
     ///@{
 
+    /**
+     * @brief Logs the user in as a moderator.
+     *
+     * @details If the authorisation type is `"simple"`, then this command expects one argument, the **global moderator password**.
+     *
+     * If the authorisation type is `"advanced"`, then it requires two arguments, the **moderator's username** and the **matching password**.
+     *
+     * @iscommand
+     */
     void cmdLogin(int argc, QStringList argv);
+
+    /**
+     * @brief Starts the authorisation type change from `"simple"` to `"advanced"`.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdChangeAuth(int argc, QStringList argv);
+
+    /**
+     * @brief Sets the root user's password.
+     *
+     * @details Accepts a single argument that will be the **root user's password**.
+     *
+     * @iscommand
+     *
+     * @pre AOClient::cmdChangeAuth()
+     */
     void cmdSetRootPass(int argc, QStringList argv);
+
+    /**
+     * @brief Adds a user to the moderators in `"advanced"` authorisation type.
+     *
+     * @details The first argument is the **user's name**, the second is their **password**.
+     *
+     * @iscommand
+     */
     void cmdAddUser(int argc, QStringList argv);
+
+    /**
+     * @brief Lists the permission of a given user.
+     *
+     * @details If called without argument, lists the caller's permissions.
+     *
+     * If called with one argument, **a username**, lists that user's permissions.
+     *
+     * @iscommand
+     */
     void cmdListPerms(int argc, QStringList argv);
+
+    /**
+     * @brief Adds permissions to a given user.
+     *
+     * @details The first argument is the **target user**, the second is the **permission** (in string form) to add to that user.
+     *
+     * @iscommand
+     */
     void cmdAddPerms(int argc, QStringList argv);
+
+    /**
+     * @brief Removes permissions from a given user.
+     *
+     * @details The first argument is the **target user**, the second is the **permission** (in string form) to remove from that user.
+     *
+     * @iscommand
+     */
     void cmdRemovePerms(int argc, QStringList argv);
+
+    /**
+     * @brief Lists all users in the server's database.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdListUsers(int argc, QStringList argv);
+
+    /**
+     * @brief Logs the caller out from their moderator user.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdLogout(int argc, QStringList argv);
 
     ///@}
@@ -633,21 +710,160 @@ class AOClient : public QObject {
       */
     ///@{
 
+    /**
+     * @brief Promotes a client to CM status.
+     *
+     * @details If called without arguments, promotes the caller.
+     *
+     * If called with a **user ID** as an argument, and the caller is a CM, promotes the target client to CM status.
+     *
+     * @iscommand
+     */
     void cmdCM(int argc, QStringList argv);
+
+    /**
+     * @brief Removes the CM status from the caller.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdUnCM(int argc, QStringList argv);
+
+    /**
+     * @brief Invites a client to the area.
+     *
+     * @details Needs a **user ID** as an argument.
+     *
+     * @iscommand
+     *
+     * @see AreaData::LOCKED and AreaData::SPECTATABLE for the benefits of being invited.
+     */
     void cmdInvite(int argc, QStringList argv);
+
+    /**
+     * @brief Uninvites a client to the area.
+     *
+     * @details Needs a **user ID** as an argument.
+     *
+     * @iscommand
+     *
+     * @see AreaData::LOCKED and AreaData::SPECTATABLE for the benefits of being invited.
+     */
     void cmdUnInvite(int argc, QStringList argv);
+
+    /**
+     * @brief Locks the area.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     *
+     * @see AreaData::LOCKED
+     */
     void cmdLock(int argc, QStringList argv);
+
+    /**
+     * @brief Sets the area to spectatable.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     *
+     * @see AreaData::SPECTATABLE
+     */
     void cmdSpectatable(int argc, QStringList argv);
+
+    /**
+     * @brief Unlocks the area.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     *
+     * @see AreaData::FREE
+     */
     void cmdUnLock(int argc, QStringList argv);
+
+    /**
+     * @brief Lists all clients in all areas.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdGetAreas(int argc, QStringList argv);
+
+    /**
+     * @brief Lists all clients in the area the caller is in.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdGetArea(int argc, QStringList argv);
+
+    /**
+     * @brief Moves the caller to the area with the given ID.
+     *
+     * @details Takes an **area ID** as an argument.
+     *
+     * @iscommand
+     */
     void cmdArea(int argc, QStringList argv);
+
+    /**
+     * @brief Kicks a client from the area, moving them back to the default area.
+     *
+     * @details Takes one argument, the **client's ID** to kick.
+     *
+     * @iscommand
+     */
     void cmdAreaKick(int argc, QStringList argv);
+
+    /**
+     * @brief Changes the background of the current area.
+     *
+     * @details Takes the **background's internal name** (generally the background's directory's name for the clients) as the only argument.
+     *
+     * @iscommand
+     */
     void cmdSetBackground(int argc, QStringList argv);
+
+    /**
+     * @brief Locks the background, preventing it from being changed.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdBgLock(int argc, QStringList argv);
+
+    /**
+     * @brief Unlocks the background, allowing it to be changed again.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdBgUnlock(int argc, QStringList argv);
+
+    /**
+     * @brief Changes the status of the current area.
+     *
+     * @details Takes a **status** as an argument. See AreaData::Status for permitted values.
+     *
+     * @iscommand
+     */
     void cmdStatus(int argc, QStringList argv);
+
+    /**
+     * @brief Returns the currently playing music in the area, and who played it.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdCurrentMusic(int argc, QStringList argv);
 
     ///@}
@@ -972,7 +1188,7 @@ class AOClient : public QObject {
      * @brief Describes a command's details.
      */
     struct CommandInfo {
-        unsigned long long acl_mask; //!< The privileges necessary to be able to run the command. @see ACLFlags.
+        unsigned long long acl_mask; //!< The permissions necessary to be able to run the command. @see ACLFlags.
         int minArgs; //!< The minimum mandatory arguments needed for the command to function.
         void (AOClient::*action)(int, QStringList);
     };

include/db_manager.h

@@ -108,24 +108,24 @@ public:
      * @param username The username clients can use to log in with.
      * @param salt The salt to obfuscate the password with.
      * @param password The user's password.
-     * @param acl The user's authority bitflag -- what special privileges does the user have.
+     * @param acl The user's authority bitflag -- what special permissions does the user have.
      *
      * @return False if the user already exists, true if the user was successfully created.
      *
      * @see AOClient::cmdLogin() and AOClient::cmdLogout() for the username and password's contexts.
-     * @see AOClient::ACLFlags for the potential special privileges a user may have.
+     * @see AOClient::ACLFlags for the potential special permissions a user may have.
      */
     bool createUser(QString username, QString salt, QString password, unsigned long long acl);
 
     /**
-     * @brief Gets the privileges of a given user.
+     * @brief Gets the permissions of a given user.
      *
      * @param moderator_name The authorised user's name.
      *
      * @return `0` if `moderator_name` is empty, `0` if such user does not exist in the Users table,
-     * or the primitive representation of an AOClient::ACLFlags privilege matrix if neither of the above are true.
+     * or the primitive representation of an AOClient::ACLFlags permission matrix if neither of the above are true.
      *
-     * @see AOClient::ACLFlags for the potential privileges a user may have.
+     * @see AOClient::ACLFlags for the potential permissions a user may have.
      */
     unsigned long long getACL(QString moderator_name);
 
@@ -141,33 +141,33 @@ public:
     bool authenticate(QString username, QString password);
 
     /**
-     * @brief Updates the privileges of a given user.
+     * @brief Updates the permissions of a given user.
      *
-     * @details This function can add or remove privileges as needed.
+     * @details This function can add or remove permissions as needed.
-     * `acl` determines what privileges are modified, while `mode` determines whether said privileges are
+     * `acl` determines what permissions are modified, while `mode` determines whether said permissions are
      * added or removed.
      *
-     * `acl` **is not** the user's current privileges *or* the sum privileges you want for the user at the end
+     * `acl` **is not** the user's current permissions *or* the sum permissions you want for the user at the end
-     * -- it is the 'difference' between the user's current and desired privileges.
+     * -- it is the 'difference' between the user's current and desired permissions.
      *
-     * If `acl` is `"NONE"`, then no matter the mode, the user's privileges are cleared.
+     * If `acl` is `"NONE"`, then no matter the mode, the user's permissions are cleared.
      *
      * For some practical examples, consult this example table:
      *
-     * | Starting privileges |    `acl`    | `mode`  | Resulting privileges |
+     * | Starting permissions |    `acl`    | `mode`  | Resulting permissions |
-     * | ------------------: | :---------: | :-----: | :------------------- |
+     * | -------------------: | :---------: | :-----: | :-------------------- |
-     * | KICK                | BAN         | `TRUE`  | KICK, BAN            |
+     * | KICK                 | BAN         | `TRUE`  | KICK, BAN             |
-     * | BAN, KICK           | BAN         | `TRUE`  | KICK, BAN            |
+     * | BAN, KICK            | BAN         | `TRUE`  | KICK, BAN             |
-     * | KICK                | BAN, BGLOCK | `TRUE`  | KICK, BAN, BGLOCK    |
+     * | KICK                 | BAN, BGLOCK | `TRUE`  | KICK, BAN, BGLOCK     |
-     * | BGLOCK, BAN, KICK   | NONE        | `TRUE`  | NONE                 |
+     * | BGLOCK, BAN, KICK    | NONE        | `TRUE`  | NONE                  |
-     * | KICK                | BAN         | `FALSE` | KICK                 |
+     * | KICK                 | BAN         | `FALSE` | KICK                  |
-     * | BAN, KICK           | BAN         | `FALSE` | KICK                 |
+     * | BAN, KICK            | BAN         | `FALSE` | KICK                  |
-     * | BGLOCK, BAN, KICK   | BAN, BGLOCK | `FALSE` | KICK                 |
+     * | BGLOCK, BAN, KICK    | BAN, BGLOCK | `FALSE` | KICK                  |
-     * | BGLOCK, BAN, KICK   | NONE        | `FALSE` | NONE                 |
+     * | BGLOCK, BAN, KICK    | NONE        | `FALSE` | NONE                  |
      *
-     * @param username The username of the user whose privileges should be updated.
+     * @param username The username of the user whose permissions should be updated.
-     * @param acl The primitive representation of the privilege matrix being modified.
+     * @param acl The primitive representation of the permission matrix being modified.
-     * @param mode If true, the privileges described in `acl` are *added* to the user;
+     * @param mode If true, the permissions described in `acl` are *added* to the user;
      * if false, they are removed instead.
      *
      * @return True if the modification was successful, false if the user does not exist in the records.