Document merged changes from master

include/advertiser.h

@@ -96,10 +96,7 @@ class Advertiser : public QObject {
     QString ip;
 
     /**
-     * @copydoc ConfigManager::server_settings::port
+     * @copydoc ConfigManager::server_settings::ms_port
-     *
-     * @bug Because of a typo in the code, this also replaces #local_port, thus clients will have to attempt
-     * to connect through the same port as the connection is established to the master server.
      */
     int port;
 
@@ -109,7 +106,7 @@ class Advertiser : public QObject {
     int ws_port;
 
     /**
-     * @copydoc ConfigManager::server_settings::local_port
+     * @copydoc ConfigManager::server_settings::port
      *
      * @bug See #port.
      */

include/aoclient.h

@@ -70,6 +70,10 @@ class AOClient : public QObject {
      * @see #ipid
      */
     QString getIpid();
+
+    /**
+     * @brief Calculates the client's IPID based on a hashed version of its IP.
+     */
     void calculateIpid();
 
     /**
@@ -146,6 +150,9 @@ class AOClient : public QObject {
      */
     bool global_enabled = true;
 
+    /**
+     * @brief If true, the client may not use in-character chat.
+     */
     bool is_muted = false;
     
     /**
@@ -189,8 +196,19 @@ class AOClient : public QObject {
         {"SUPER",          ~0ULL      },
     };
 
+    /**
+     * @brief If true, the client's in-character messages will have their word order randomised.
+     */
     bool is_shaken;
+
+    /**
+     * @brief If true, the client's in-character messages will have their vowels (English alphabet only) removed.
+     */
     bool is_disemvoweled;
+
+    /**
+     * @brief If true, the client's in-character messages will be overwritten by a randomly picked predetermined message.
+     */
     bool is_gimped;
 
   public slots:
@@ -602,7 +620,25 @@ class AOClient : public QObject {
      * @iscommand
      */
     void cmdHelp(int argc, QStringList argv);
+
+    /**
+     * @brief Gets or sets the server's Message Of The Day.
+     *
+     * @details If called without arguments, gets the MOTD.
+     *
+     * If it has any number of arguments, it is set as the **MOTD**.
+     *
+     * @iscommand
+     */
     void cmdMOTD(int argc, QStringList argv);
+
+    /**
+     * @brief Gives a very brief description of Akashi.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdAbout(int argc, QStringList argv);
     
     /**
@@ -649,6 +685,14 @@ class AOClient : public QObject {
      * @iscommand
      */
     void cmdAddUser(int argc, QStringList argv);
+
+    /**
+     * @brief Removes a user from the moderators in `"advanced"` authorisation type.
+     *
+     * @details Takes the **targer user's name** as the argument.
+     *
+     * @iscommand
+     */
     void cmdRemoveUser(int argc, QStringList argv);
 
     /**
@@ -887,8 +931,14 @@ class AOClient : public QObject {
      * @brief Bans a client from the server, forcibly severing its connection to the server,
      * and disallowing their return.
      *
-     * @details The first argument is the **target's IPID**, while the remaining arguments are the **reason**
+     * @details The first argument is the **target's IPID**, the second is the **reason** why the client
-     * the client was banned. Both arguments are mandatory.
+     * was banned, the third is the **duration**.
+     *
+     * Both the reason and the duration must be in quotation marks.
+     *
+     * The duration can be `"perma"`, meaning a forever ban, otherwise, it must be given in the format of `"YYyWWwDDdHHhMMmSSs"` to
+     * mean a YY years, WW weeks, DD days, HH hours, MM minutes and SS seconds long ban. Any of these may be left out, for example,
+     * `"1h30m"` for a 1.5 hour long ban.
      *
      * Besides banning, this command kicks all clients having the given IPID,
      * thus a multiclienting user will have all their clients be kicked from the server.
@@ -899,6 +949,14 @@ class AOClient : public QObject {
      * @iscommand
      */
     void cmdBan(int argc, QStringList argv);
+
+    /**
+     * @brief Removes a ban from the database.
+     *
+     * @details Takes a single argument, the **ID** of the ban.
+     *
+     * @iscommand
+     */
     void cmdUnBan(int argc, QStringList argv);
 
     /**
@@ -913,11 +971,67 @@ class AOClient : public QObject {
      * @iscommand
      */
     void cmdKick(int argc, QStringList argv);
+
+    /**
+     * @brief Sends out a decorated global message, for announcements.
+     *
+     * @details The arguments are **the message** that the client wants to send.
+     *
+     * @iscommand
+     *
+     * @see AOClient::cmdG()
+     */
     void cmdAnnounce(int argc, QStringList argv);
+
+    /**
+     * @brief Sends a message in the server-wide, moderator only chat.
+     *
+     * @details The arguments are **the message** that the client wants to send.
+     *
+     * @iscommand
+     */
     void cmdM(int argc, QStringList argv);
+
+    /**
+     * @brief Sends out a global message that is marked with an `[M]` to mean it is coming from a moderator.
+     *
+     * @details The arguments are **the message** that the client wants to send.
+     *
+     * @iscommand
+     *
+     * @see AOClient::cmdG()
+     */
     void cmdGM(int argc, QStringList argv);
+
+    /**
+     * @brief Mutes a client.
+     *
+     * @details The only argument is the **target client's user ID**.
+     *
+     * @iscommand
+     *
+     * @see #is_muted
+     */
     void cmdMute(int argc, QStringList argv);
+
+    /**
+     * @brief Removes the muted status a client.
+     *
+     * @details The only argument is the **target client's user ID**.
+     *
+     * @iscommand
+     *
+     * @see #is_muted
+     */
     void cmdUnmute(int argc, QStringList argv);
+
+    /**
+     * @brief Lists the last five bans made on the server.
+     *
+     * @details No arguments.
+     *
+     * @iscommand
+     */
     void cmdBans(int argc, QStringList argv);
 
     ///@}
@@ -1031,6 +1145,14 @@ class AOClient : public QObject {
      * @see AreaData::EvidenceMod
      */
     void cmdEvidenceMod(int argc, QStringList argv);
+
+    /**
+     * @brief Changes the subtheme of the clients in the current area.
+     *
+     * @details The only argument is the **name of the subtheme**. Reloading is always forced.
+     *
+     * @iscommand
+     */
     void cmdSubTheme(int argc, QStringList argv);
     
     ///@}
@@ -1179,6 +1301,26 @@ class AOClient : public QObject {
      * @param Type The type of the dice-rolling being done.
      */
     void diceThrower(int argc, QStringList argv, RollType Type);
+
+    /**
+     * @brief Interprets an expression of time into amount of seconds.
+     *
+     * @param input A string in the format of `"XXyXXwXXdXXhXXmXXs"`, where every `XX` is some integer.
+     * There is no limit on the length of the integers, the `XX` text is just a placeholder, and is not intended to
+     * indicate a limit of two digits maximum.
+     *
+     * The string gets interpreted as follows:
+     * * `XXy` is parsed into `XX` amount of years,
+     * * `XXw` is parsed into `XX` amount of weeks,
+     * * `XXd` is parsed into `XX` amount of days,
+     * * `XXh` is parsed into `XX` amount of hours,
+     * * `XXm` is parsed into `XX` amount of minutes, and
+     * * `XXs` is parsed into `XX` amount of seconds.
+     *
+     * Any of these may be left out, but the order must be kept (i.e., `"10s5y"` is a malformed text).
+     *
+     * @return The parsed text, converted into their respective durations, summed up, then converted into seconds.
+     */
     long long parseTime(QString input);
 
     ///@}

include/area_data.h

@@ -35,6 +35,13 @@ class Logger;
 class AreaData : public QObject {
   Q_OBJECT
   public:
+    /**
+     * @brief Constructor for the AreaData class.
+     *
+     * @param p_name The name of the area. This must be in the format of `"X:YYYYYY"`, where `X` is an integer,
+     * and `YYYYYY` is the actual name of the area.
+     * @param p_index The index of the area in the area list.
+     */
     AreaData(QString p_name, int p_index);
 
     /**
@@ -61,6 +68,9 @@ class AreaData : public QObject {
      */
     int index;
 
+    /**
+     * @brief A list of the character IDs of all characters taken.
+     */
     QList<int> characters_taken;
 
     /**

include/db_manager.h

@@ -82,30 +82,73 @@ public:
     QString getBanReason(QHostAddress ip);
 
     /**
-     * @brief Overloaded function for getBanReason(QHostAddress). Returns based on HDID instead of IP.
+     * @overload
-     *
-     * @param hdid The hardware ID whose ban reason needs to be returned.
-     *
-     * @return The ban reason if the hardware ID is actually banned,
-     * or `"Ban reason not found."` if the hardware ID is not actually banned.
      */
     QString getBanReason(QString hdid);
-    long long getBanDuration(QString hdid);
+
+    /**
+     * @brief Returns the reason the given IP address was banned with.
+     *
+     * @param ip The IP address whose ban duration to get.
+     *
+     * @return The ban duration if the IP address is actually banned,
+     * or `-1` if the IP address is not actually banned.
+     */
     long long getBanDuration(QHostAddress ip);
-    int getBanID(QString hdid);
+
+    /**
+     * @overload
+     */
+    long long getBanDuration(QString hdid);
+
+    /**
+     * @brief Gets the ID number of a given ban.
+     *
+     * @param ip The IP address whose associated ban's ID we need.
+     *
+     * @return The ID of the ban if the IP address is actually banned,
+     * or `-1` if the IP address is not actually banned.
+     */
     int getBanID(QHostAddress ip);
 
+    /**
+     * @overload
+     */
+    int getBanID(QString hdid);
+
+    /**
+     * @brief Details about a ban.
+     */
     struct BanInfo {
-        QString ipid;
+        QString ipid; //!< The banned user's IPID.
-        QHostAddress ip;
+        QHostAddress ip; //!< The banned user's IP.
-        QString hdid;
+        QString hdid; //!< The banned user's hardware ID.
-        unsigned long time;
+        unsigned long time; //!< The time the ban was registered.
-        QString reason;
+        QString reason; //!< The reason given for the ban by the moderator who registered it.
-        long long duration;
+        long long duration; //!< The duration of the ban, in seconds.
     };
+
+    /**
+     * @brief Gets the last five bans made on the server.
+     *
+     * @return See brief description.
+     */
     QList<BanInfo> getRecentBans();
 
+    /**
+     * @brief Registers a ban into the database.
+     *
+     * @param ban The details of the ban.
+     */
     void addBan(BanInfo ban);
+
+    /**
+     * @brief Sets the duration of a given ban to 0, effectively removing the ban the associated user.
+     *
+     * @param id The ID of the ban to invalidate.
+     *
+     * @return False if no such ban exists, true if the invalidation was successful.
+     */
     bool invalidateBan(int id);
 
     /**
@@ -122,6 +165,14 @@ public:
      * @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 Deletes an authorised user from the database.
+     *
+     * @param username The username whose associated user to delete.
+     *
+     * @return False if the user didn't even exist, true if the user was successfully deleted.
+     */
     bool deleteUser(QString username);
 
     /**

include/server.h

@@ -77,9 +77,18 @@ class Server : public QObject {
      * @param ipid The IPID to look for.
      *
      * @return A pointer to the client if found, a nullpointer if not.
+     *
+     * @see Server::getClientsByIpid() to get all clients ran by the same user.
      */
     AOClient* getClient(QString ipid);
 
+    /**
+     * @brief Gets a list of pointers to all clients with the given IPID.
+     *
+     * @param ipid The IPID to look for.
+     *
+     * @return A list of clients whose IPID match. List may be empty.
+     */
     QList<AOClient*> getClientsByIpid(QString ipid);
     
     /**
@@ -196,6 +205,10 @@ class Server : public QObject {
      * @note Unused. getServerName() serves its purpose instead.
      */
     QString server_name;
+
+    /**
+     * @brief The Message Of The Day of the server, shown upon entry to the server and on request.
+     */
     QString MOTD;
 
     /**