From b2368aadd4dd917905fd25244c836c69a93bf9c6 Mon Sep 17 00:00:00 2001
From: Luke De Mouy <lukedemouydev@gmail.com>
Date: Wed, 13 Jan 2016 17:52:09 -0700
Subject: [PATCH] Document all of the member functions in the header

---
 src/library/sysadm-usermanager.cpp |  1 +
 src/library/sysadm-usermanager.h   | 84 ++++++++++++++++++++++++++++--
 2 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/src/library/sysadm-usermanager.cpp b/src/library/sysadm-usermanager.cpp
index 59ba987..af2f2f3 100644
--- a/src/library/sysadm-usermanager.cpp
+++ b/src/library/sysadm-usermanager.cpp
@@ -339,6 +339,7 @@ void UserManager::loadGroups()
 
 void UserManager::loadShells()
 {
+    shells.clear();
     QFile shellFile(chroot + "/etc/shells");
     if ( shellFile.open(QIODevice::ReadOnly) ) {
         QTextStream stream(&shellFile);
diff --git a/src/library/sysadm-usermanager.h b/src/library/sysadm-usermanager.h
index 9ec0ba6..3467395 100644
--- a/src/library/sysadm-usermanager.h
+++ b/src/library/sysadm-usermanager.h
@@ -54,35 +54,110 @@ public:
      * @param fullName The full name of the user
      * @param userName The username of the user
      * @param password The user's password
-     * @param home the user's home directory, defaults to /usr/home/$userName
      * @param shell the user's shell, defaults to /bin/tcsh
-     * @param gid the gid of the user, defaults to -1, which means to leave it up to autogen
-     * @param uid the uid of the user, defaults to -1, which means to leave it up to autogen
      */
     void NewUser(QString fullName, QString userName, QString password, QString shell = "/bin/tcsh");
+    /**
+     * @brief DeleteUser Deletes a user
+     * @param user the user to delete
+     */
     void DeleteUser(User user);
 
+    /**
+     * @brief GetUsers getter for the users vector
+     * @return a QVector<Users> that is a copy of the current state
+     * do not modify it, instead call functions on this class to change
+     * things and then get another copy of the vector
+     */
     const QVector<User> GetUsers();
+    /**
+     * @brief GetUser get a particular user by their UID
+     * @param id the UID of the user to get
+     * @return the user with the UID specified, if not found
+     * returns a blank User
+     */
     const User GetUser(int id);
+
+    /**
+     * @brief GetUser get a particular user by their UID
+     * @param userName the username of the user to get
+     * @return the user with the user name specified, if not found
+     * returns a blank User
+     */
     const User GetUser(QString userName);
 
+    /**
+     * @brief ChangeUserPassword changes the specified user's password
+     * @param user the user to change the password of
+     * @param newPassword the new password
+     */
     void ChangeUserPassword(User user, QString newPassword);
+    /**
+     * @brief ChangeUserShell change a specified user's shell
+     * @param user the user to change the shell for
+     * @param shell the shell to change to, note that if the shell
+     * is not in the shells list then it does nothing
+     */
     void ChangeUserShell(User user, QString shell);
+    /**
+     * @brief ChangeUserFullName change the gecos field of a user to a new name
+     * @param user the user to change the name of
+     * @param newName the name to change to
+     */
     void ChangeUserFullName(User user, QString newName);
     //#endsection
 
     //#section group actions
+    /**
+     * @brief AddUserToGroup add the specified user to the specified group
+     * @param user the user to add to the group
+     * @param group the group to add the user to
+     */
     void AddUserToGroup(User user, Group group);
+    /**
+     * @brief RemoveUserFromGroup removes the specified user from the specified group
+     * @param user the user to remove from the group
+     * @param group the group to remove the user from
+     */
     void RemoveUserFromGroup(User user, Group group);
 
+    /**
+     * @brief NewGroup creates a new group
+     * @param name the name of the new group
+     * @param Users a list of users to add to the group
+     */
     void NewGroup(QString name, QStringList Users = QStringList());
+    /**
+     * @brief DeleteGroup delete a specified group
+     * @param group the group to delete
+     */
     void DeleteGroup(Group group);
 
+    /**
+     * @brief GetGroups get the internal list of groups
+     * @return a QVector<Group> that is a copy of the current state
+     * do not modify it, instead call functions on this class to change
+     * things and then get another copy of the vector
+     */
     const QVector<Group> GetGroups();
+    /**
+     * @brief getGroup get a specified group by their gid
+     * @param id the gid of the group to get
+     * @return the group with the specified gid
+     */
     const Group getGroup(int id);
+    /**
+     * @brief getGroup get a specified group by their name
+     * @param name the name of the group to get
+     * @return the group with the specified name
+     */
     const Group getGroup(QString name);
     //#endsection
 
+    /**
+     * @brief GetShells the list of shells that are currently installed on the system
+     * @return a QStringList of shells on the system
+     */
     const QStringList GetShells();
 
 private:
@@ -91,8 +166,11 @@ private:
     QStringList shells;
     QString chroot;
 
+    //loads the users from /etc/passwd
     void loadUsers();
+    //load the groups from /etc/group
     void loadGroups();
+    //load the shells from /etc/shells
     void loadShells();
 };
 }