added documentation to wpasupinteract

sources/netctlgui/include/netctlgui/netctlprofile.h

@@ -53,30 +53,30 @@ public:
       */
     ~NetctlProfile();
     /**
-     * @brief function which copies temporary profile to PROFILE_DIR
+     * @brief method which copies temporary profile to PROFILE_DIR
      * @param oldPath        path to temprorary profile
      * @return false if components are not found or command exit code is not equal to 0
-     * @return true if the function was completed without errors
+     * @return true if the method was completed without errors
      */
     bool copyProfile(const QString oldPath);
     /**
-     * @brief function which creates temporary profile
+     * @brief method which creates temporary profile
      * @param profile        profile name
      * @param settings       profile configuration. All available keys will be printed to the profile
      * @return temporary profile name
      */
     QString createProfile(const QString profile, const QMap<QString, QString> settings);
     /**
-     * @brief function which reads settings from profile
+     * @brief method which reads settings from profile
      * @param profile        profile name
      * @return settings from profile
      */
     QMap<QString, QString> getSettingsFromProfile(const QString profile);
     /**
-     * @brief function which removes profile
+     * @brief method which removes profile
      * @param profile        profile name
      * @return false if components are not found or command exit code is not equal to 0
-     * @return true if the function was completed without errors
+     * @return true if the method was completed without errors
      */
     bool removeProfile(const QString profile);
 
@@ -86,11 +86,11 @@ private:
      */
     bool debug;
     /**
-     * @brief path to directory which contains profiles. Defaults is /etc/netctl
+     * @brief path to directory which contains profiles. Default is "/etc/netctl"
      */
     QDir *profileDirectory;
     /**
-     * @brief path to sudo command. Defaults is /usr/bin/kdesu
+     * @brief path to sudo command. Default is "/usr/bin/kdesu"
      */
     QString sudoCommand;
 };

sources/netctlgui/include/netctlgui/wpasupinteract.h

@@ -14,6 +14,14 @@
  *   You should have received a copy of the GNU General Public License     *
  *   along with netctl-gui. If not, see http://www.gnu.org/licenses/       *
  ***************************************************************************/
+/**
+ * @file wpasupinteract.h
+ * Header of netctlgui library
+ * @author Evgeniy Alekseev
+ * @copyright GPLv3
+ * @bug https://github.com/arcan1s/netctl-gui/issues
+ */
+
 
 #ifndef WPASUPINTERACT_H
 #define WPASUPINTERACT_H
@@ -25,40 +33,152 @@
 
 class Netctl;
 
+/**
+ * @brief The WpaSup class interacts with wpa_supplicant
+ */
 class WpaSup : public QObject
 {
     Q_OBJECT
 
 public:
+    /**
+     * @brief WpaSup class constructor
+     * @param debugCmd       show debug messages
+     * @param settings       default settings. Needed keys are
+     *                       CTRL_DIR (path to ctrl_directory),
+     *                       CTRL_GROUP (group which is owner of CTRL_DIR),
+     *                       IFACE_DIR (path to directory with interfaces),
+     *                       PREFERED_IFACE (prefered interface for WiFi),
+     *                       PID_FILE (wpa_supplicant PID file),
+     *                       SUDO_PATH (path to sudo command),
+     *                       WPACLI_PATH (path to wpa_cli command),
+     *                       WPA_DRIVERS (wpa_supplicant drivers comma separated),
+     *                       WPASUP_PATH (path to wpa_supplicant command)
+     */
     explicit WpaSup(const bool debugCmd = false,
                     const QMap<QString, QString> settings = QMap<QString, QString>());
+    /**
+     * @brief WpaSup class destructor
+     */
     ~WpaSup();
     // general information
-    QString existentProfile(const QString profile);
+    /**
+     * @brief method which gets profile name by ESSID
+     * @param essid          ESSID name
+     * @return profile name
+     */
+    QString existentProfile(const QString essid);
+    /**
+     * @brief method which gets interface list from PREFERED_IFACE and IFACE_DIR
+     * @return interface list. If PREFERED_IFACE is not empty it will be first element
+     */
     QStringList getInterfaceList();
-    bool isProfileActive(const QString profile);
+    /**
-    bool isProfileExists(const QString profile);
+     * @brief method which checks profile status by ESSID
+     * @param essid          ESSID name
+     * @return false if profile is inactive
+     * @return true if profile is active
+     */
+    bool isProfileActive(const QString essid);
+    /**
+     * @brief method which checks profile existence by ESSID
+     * @param essid          ESSID name
+     * @return false if profile does not exist
+     * @return true if profile exists
+     */
+    bool isProfileExists(const QString essid);
 
 public slots:
     // functions
+    /**
+     * @brief method which scans WiFi networks
+     * @return list of profiles. Available information is [NAME, NETCTL_STATUS, SIGNAL, SECUITY]:
+     *         NAME is WiFi point name or "<hidden>",
+     *         NETCTL_STATUS may be "new", "exist (active)", "exist (inactive)",
+     *         SIGNAL is Wifi point signal,
+     *         SECURITY may be "WPA2", "WEP", "WEP", "none"
+     */
     QList<QStringList> scanWifi();
+    /**
+     * @brief method which calls wpa_supplicant
+     * @return false if components are not found or command exit code is not equal to 0
+     * @return true if the method was completed without errors
+     */
     bool startWpaSupplicant();
+    /**
+     * @brief method which send TERMINATE signal to wpa_supplicant
+     * @return false if components are not found or command exit code is not equal to 0
+     * @return true if the method was completed without errors
+     */
     bool stopWpaSupplicant();
 
 private:
+    /**
+     * @brief Netctl class
+     */
     Netctl *netctlCommand;
+    /**
+     * @brief show debug messages
+     */
     bool debug;
+    CTRL_DIR (path to ctrl_directory),
+         *                       CTRL_GROUP (group which is owner of CTRL_DIR),
+         *                       IFACE_DIR (path to directory with interfaces),
+         *                       PREFERED_IFACE (prefered interface for WiFi),
+         *                       PID_FILE (wpa_supplicant PID file),
+         *                       SUDO_PATH (path to sudo command),
+         *                       WPACLI_PATH (path to wpa_cli command),
+         *                       WPA_DRIVERS (wpa_supplicant drivers comma separated),
+         *                       WPASUP_PATH (path to wpa_supplicant command)
+    /**
+     * @brief path to ctrl_directory. Defaults is "/run/wpa_supplicant_netctl-gui"
+     */
     QString ctrlDir;
+    /**
+     * @brief group which is owner of CTRL_DIR. Default is "users"
+     */
     QString ctrlGroup;
+    /**
+     * @brief path to directory with interfaces. Default is "/sys/class/net/"
+     */
     QDir *ifaceDirectory;
+    /**
+     * @brief prefered interface for WiFi. Default is ""
+     */
     QString mainInterface;
+    /**
+     * @brief wpa_supplicant PID file. Default is "/run/wpa_supplicant_netctl-gui.pid"
+     */
     QString pidFile;
+    /**
+     * @brief path to sudo command. Default is "/usr/bin/kdesu"
+     */
     QString sudoCommand;
+    /**
+     * @brief path to wpa_cli command. Default is "/usr/bin/wpa_cli"
+     */
     QString wpaCliPath;
+    /**
+     * @brief wpa_supplicant drivers comma separated. Default is "nl80211,wext"
+     */
     QString wpaDrivers;
+    /**
+     * @brief path to wpa_supplicant command. Default is "/usr/bin/wpa_supplicant"
+     */
     QString wpaSupPath;
     // functions
+    /**
+     * @brief method which calls wpa_cli
+     * @param commandLine    command which will be send to wpa_cli
+     * @return false if components are not found or command exit code is not equal to 0
+     * @return true if the method was completed without errors
+     */
     bool wpaCliCall(const QString commandLine);
+    /**
+     * @brief method which calls wpa_cli and returns its output
+     * @param commandLine    command which will be send to wpa_cli
+     * @return wpa_cli output
+     */
     QString getWpaCliOutput(const QString commandLine);
 };
 

sources/netctlgui/src/netctlinteract.cpp

@@ -15,6 +15,7 @@
  *   along with netctl-gui. If not, see http://www.gnu.org/licenses/       *
  ***************************************************************************/
 
+
 #include <QDebug>
 #include <QFile>
 #include <QProcess>

sources/netctlgui/src/wpasupinteract.cpp

@@ -14,6 +14,14 @@
  *   You should have received a copy of the GNU General Public License     *
  *   along with netctl-gui. If not, see http://www.gnu.org/licenses/       *
  ***************************************************************************/
+/**
+ * @file wpasupinteract.cpp
+ * Source code of netctlgui library
+ * @author Evgeniy Alekseev
+ * @copyright GPLv3
+ * @bug https://github.com/arcan1s/netctl-gui/issues
+ */
+
 
 #include <QDebug>
 #include <QProcess>
@@ -23,6 +31,12 @@
 #include <netctlgui/wpasupinteract.h>
 
 
+/**
+ * @class WpaSup
+ */
+/**
+ * @fn WpaSup
+ */
 WpaSup::WpaSup(const bool debugCmd, const QMap<QString, QString> settings)
     : debug(debugCmd)
 {
@@ -30,22 +44,40 @@ WpaSup::WpaSup(const bool debugCmd, const QMap<QString, QString> settings)
 
     if (settings.contains(QString("CTRL_DIR")))
         ctrlDir = settings[QString("CTRL_DIR")];
+    else
+        ctrlDir = QString("/run/wpa_supplicant_netctl-gui");
     if (settings.contains(QString("CTRL_GROUP")))
         ctrlGroup = settings[QString("CTRL_GROUP")];
+    else
+        ctrlGroup = QString("users");
     if (settings.contains(QString("IFACE_DIR")))
         ifaceDirectory = new QDir(settings[QString("IFACE_DIR")]);
+    else
+        ifaceDirectory = new QDir(QString("/sys/class/net/"));
     if (settings.contains(QString("PREFERED_IFACE")))
         mainInterface = settings[QString("PREFERED_IFACE")];
+    else
+        mainInterface = QString("");
     if (settings.contains(QString("PID_FILE")))
         pidFile = settings[QString("PID_FILE")];
+    else
+        pidFile = QString("/run/wpa_supplicant_netctl-gui.pid");
     if (settings.contains(QString("SUDO_PATH")))
         sudoCommand = settings[QString("SUDO_PATH")];
+    else
+        sudoCommand = QString("/usr/bin/kdesu");
     if (settings.contains(QString("WPACLI_PATH")))
         wpaCliPath = settings[QString("WPACLI_PATH")];
+    else
+        wpaCliPath = QString("/usr/bin/wpa_cli");
     if (settings.contains(QString("WPA_DRIVERS")))
         wpaDrivers = settings[QString("WPA_DRIVERS")];
+    else
+        wpaDrivers = QString("nl80211,wext");
     if (settings.contains(QString("WPASUP_PATH")))
         wpaSupPath = settings[QString("WPASUP_PATH")];
+    else
+        wpaSupPath = QString("/usr/bin/wpa_supplicant");
 
     // terminate old loaded profile
     if (QFile(pidFile).exists() || QDir(ctrlDir).exists())
@@ -53,6 +85,9 @@ WpaSup::WpaSup(const bool debugCmd, const QMap<QString, QString> settings)
 }
 
 
+/**
+ * @fn ~WpaSup
+ */
 WpaSup::~WpaSup()
 {
     if (debug) qDebug() << "[WpaSup]" << "[~WpaSup]";
@@ -64,21 +99,27 @@ WpaSup::~WpaSup()
 
 
 // general information
-QString WpaSup::existentProfile(const QString profile)
+/**
+ * @fn existentProfile
+ */
+QString WpaSup::existentProfile(const QString essid)
 {
     if (debug) qDebug() << "[WpaSup]" << "[existentProfile]";
-    if (debug) qDebug() << "[WpaSup]" << "[existentProfile]" << ":" << "Profile" << profile;
+    if (debug) qDebug() << "[WpaSup]" << "[existentProfile]" << ":" << "ESSID" << essid;
 
     QString profileFile = QString("");
     QList<QStringList> profileList = netctlCommand->getProfileList();
     for (int i=0; i<profileList.count(); i++)
-        if (profile == netctlCommand->getSsidFromProfile(profileList[i][0]))
+        if (essid == netctlCommand->getSsidFromProfile(profileList[i][0]))
             profileFile = profileList[i][0];
 
     return profileFile;
 }
 
 
+/**
+ * @fn getInterfaceList
+ */
 QStringList WpaSup::getInterfaceList()
 {
     if (debug) qDebug() << "[WpaSup]" << "[getInterfaceList]";
@@ -103,36 +144,49 @@ QStringList WpaSup::getInterfaceList()
 }
 
 
-bool WpaSup::isProfileActive(const QString profile)
+/**
+ * @fn isProfileActive
+ */
+bool WpaSup::isProfileActive(const QString essid)
 {
     if (debug) qDebug() << "[WpaSup]" << "[isProfileActive]";
-    if (debug) qDebug() << "[WpaSup]" << "[isProfileActive]" << ":" << "Profile" << profile;
+    if (debug) qDebug() << "[WpaSup]" << "[isProfileActive]" << ":" << "ESSID" << essid;
 
     QString profileFile;
     QList<QStringList> profileList = netctlCommand->getProfileList();
     for (int i=0; i<profileList.count(); i++)
-        if (profile == netctlCommand->getSsidFromProfile(profileList[i][0]))
+        if (essid == netctlCommand->getSsidFromProfile(profileList[i][0])) {
             profileFile = profileList[i][0];
+            break;
+        }
 
     return netctlCommand->isProfileActive(profileFile);
 }
 
 
-bool WpaSup::isProfileExists(const QString profile)
+/**
+ * @fn isProfileExists
+ */
+bool WpaSup::isProfileExists(const QString essid)
 {
     if (debug) qDebug() << "[WpaSup]" << "[isProfileExists]";
-    if (debug) qDebug() << "[WpaSup]" << "[isProfileExists]" << ":" << "Profile" << profile;
+    if (debug) qDebug() << "[WpaSup]" << "[isProfileExists]" << ":" << "ESSID" << essid;
 
     bool exists = false;
     QList<QStringList> profileList = netctlCommand->getProfileList();
     for (int i=0; i<profileList.count(); i++)
-        if (profile == netctlCommand->getSsidFromProfile(profileList[i][0]))
+        if (essid == netctlCommand->getSsidFromProfile(profileList[i][0])) {
             exists = true;
+            break;
+        }
 
     return exists;
 }
 
 
+/**
+ * @fn scanWifi
+ */
 QList<QStringList> WpaSup::scanWifi()
 {
     if (debug) qDebug() << "[WpaSup]" << "[scanWifi]";
@@ -203,6 +257,9 @@ QList<QStringList> WpaSup::scanWifi()
 }
 
 
+/**
+ * @fn startWpaSupplicant
+ */
 bool WpaSup::startWpaSupplicant()
 {
     if (debug) qDebug() << "[WpaSup]" << "[startWpaSupplicant]";
@@ -251,6 +308,9 @@ bool WpaSup::startWpaSupplicant()
 }
 
 
+/**
+ * @fn stopWpaSupplicant
+ */
 bool WpaSup::stopWpaSupplicant()
 {
     if (debug) qDebug() << "[WpaSup]" << "[stopWpaSupplicant]";
@@ -260,6 +320,9 @@ bool WpaSup::stopWpaSupplicant()
 
 
 // functions
+/**
+ * @fn wpaCliCall
+ */
 bool WpaSup::wpaCliCall(const QString commandLine)
 {
     if (debug) qDebug() << "[WpaSup]" << "[wpaCliCall]";
@@ -294,6 +357,9 @@ bool WpaSup::wpaCliCall(const QString commandLine)
 }
 
 
+/**
+ * @fn getWpaCliOutput
+ */
 QString WpaSup::getWpaCliOutput(const QString commandLine)
 {
     if (debug) qDebug() << "[WpaSup]" << "[getWpaCliOutput]";