Update UserManager documentation and comments

diff --git a/include/usermanager.h b/include/usermanager.h
index 941569e8c02e7af1813ec95468fd7e924a3d36d8..1b1b0b600f703d0b2a49dc01114e06e6eeec09a7 100644 (file)
--- a/include/usermanager.h
+++ b/include/usermanager.h
@@ -70,12 +70,11 @@ class CoreExport UserManager : public fakederef<UserManager>
         */
        ~UserManager();
 
-       /** Client list, a hash_map containing all clients, local and remote
+       /** Nickname string -> User* map. Contains all users, including unregistered ones.
         */
        user_hash clientlist;
 
-       /** Client list stored by UUID. Contains all clients, and is updated
-        * automatically by the constructor and destructor of User.
+       /** UUID -> User* map. Contains all users, including unregistered ones.
         */
        user_hash uuidlist;
 
@@ -88,7 +87,8 @@ class CoreExport UserManager : public fakederef<UserManager>
         */
        unsigned int unregistered_count;
 
-       /** Perform background user events such as PING checks
+       /** Perform background user events for all local users such as PING checks, registration timeouts,
+        * penalty management and recvq processing for users who have data in their recvq due to throttling.
         */
        void DoBackgroundUserStuff();
 
@@ -98,22 +98,24 @@ class CoreExport UserManager : public fakederef<UserManager>
         */
        bool AllModulesReportReady(LocalUser* user);
 
-       /** Add a client to the system.
-        * This will create a new User, insert it into the user_hash,
-        * initialize it as not yet registered, and add it to the socket engine.
-        * @param socket The socket id (file descriptor) this user is on
-        * @param via The socket that this user connected using
+       /** Handle a client connection.
+        * Creates a new LocalUser object, inserts it into the appropriate containers,
+        * initializes it as not yet registered, and adds it to the socket engine.
+        *
+        * The new user may immediately be quit after being created, for example if the user limit
+        * is reached or if the user is banned.
+        * @param socket File descriptor of the connection
+        * @param via Listener socket that this user connected to
         * @param client The IP address and client port of the user
         * @param server The server IP address and port used by the user
-        * @return This function has no return value, but a call to AddClient may remove the user.
         */
        void AddUser(int socket, ListenSocket* via, irc::sockets::sockaddrs* client, irc::sockets::sockaddrs* server);
 
-       /** Disconnect a user gracefully
+       /** Disconnect a user gracefully.
+        * When this method returns the user provided will be quit, but the User object will continue to be valid and will be deleted at the end of the current main loop iteration.
         * @param user The user to remove
         * @param quitreason The quit reason to show to normal users
         * @param operreason The quit reason to show to opers, can be NULL if same as quitreason
-        * @return Although this function has no return type, on exit the user provided will no longer exist.
         */
        void QuitUser(User* user, const std::string& quitreason, const std::string* operreason = NULL);
 
@@ -129,7 +131,7 @@ class CoreExport UserManager : public fakederef<UserManager>
         */
        void RemoveCloneCounts(User *user);
 
-       /** Rebuild clone counts
+       /** Rebuild clone counts. Required when <cidr> settings change.
         */
        void RehashCloneCounts();
 

diff --git a/src/usermanager.cpp b/src/usermanager.cpp
index b3ee21f2bb7b8a34686acf9ac0e030175643c6ee..12ec36ec7ce16d0db4477c5978c241508c1563cd 100644 (file)
--- a/src/usermanager.cpp
+++ b/src/usermanager.cpp
@@ -62,22 +62,17 @@ UserManager::~UserManager()
        }
 }
 
-/* add a client connection to the sockets list */
 void UserManager::AddUser(int socket, ListenSocket* via, irc::sockets::sockaddrs* client, irc::sockets::sockaddrs* server)
 {
-       /* NOTE: Calling this one parameter constructor for User automatically
-        * allocates a new UUID and places it in the hash_map.
-        */
+       // User constructor allocates a new UUID for the user and inserts it into the uuidlist
        LocalUser* const New = new LocalUser(socket, client, server);
        UserIOHandler* eh = &New->eh;
 
        ServerInstance->Logs->Log("USERS", LOG_DEBUG, "New user fd: %d", socket);
 
        this->unregistered_count++;
-
        this->clientlist[New->nick] = New;
        this->AddClone(New);
-
        this->local_users.push_front(New);
 
        if (!SocketEngine::AddFd(eh, FD_WANT_FAST_READ | FD_WANT_EDGE_WRITE))
@@ -110,16 +105,9 @@ void UserManager::AddUser(int socket, ListenSocket* via, irc::sockets::sockaddrs
                return;
        }
 
-       /*
-        * First class check. We do this again in FullConnect after DNS is done, and NICK/USER is recieved.
-        * See my note down there for why this is required. DO NOT REMOVE. :) -- w00t
-        */
+       // First class check. We do this again in LocalUser::FullConnect() after DNS is done, and NICK/USER is received.
        New->SetClass();
-
-       /*
-        * Check connect class settings and initialise settings into User.
-        * This will be done again after DNS resolution. -- w00t
-        */
+       // If the user doesn't have an acceptable connect class CheckClass() quits them
        New->CheckClass(ServerInstance->Config->CCOnConnect);
        if (New->quitting)
                return;
@@ -298,14 +286,11 @@ bool UserManager::AllModulesReportReady(LocalUser* user)
 
 /**
  * This function is called once a second from the mainloop.
- * It is intended to do background checking on all the user structs, e.g.
- * stuff like ping checks, registration timeouts, etc.
+ * It is intended to do background checking on all the users, e.g. do
+ * ping checks, registration timeouts, etc.
  */
 void UserManager::DoBackgroundUserStuff()
 {
-       /*
-        * loop over all local users..
-        */
        for (LocalList::iterator i = local_users.begin(); i != local_users.end(); )
        {
                // It's possible that we quit the user below due to ping timeout etc. and QuitUser() removes it from the list