added some comments in according to the doxigen

conventions. Some todos are left due to less knowledge about
the methods.
edited classes are sysinfo and javascriptinterface

3 files changed, 220 insertions, 1 deletions

diff --git a/src/fbgui.cpp b/src/fbgui.cpp
index 4aba08f..30a6011 100644
--- a/src/fbgui.cpp
+++ b/src/fbgui.cpp
@@ -26,7 +26,7 @@ fbgui::fbgui()
     //sil->getInfoAboutNetworkInterface();
     //sil->getInfoMainboardSerial();
 	SysInfo si;
-	si.getInfo("mbserial");
+	qxtLog->debug() << si.getInfo("mbserial");
 	si.getInfo("usb");
 
 
diff --git a/src/javascriptinterface.cpp b/src/javascriptinterface.cpp
index 5ef443e..13bcd38 100644
--- a/src/javascriptinterface.cpp
+++ b/src/javascriptinterface.cpp
@@ -6,18 +6,48 @@
 //-------------------------------------------------------------------------------------------------------
 //                                         Initialisation
 //-------------------------------------------------------------------------------------------------------
+/**
+ * A constructor.
+ *
+ * @param parent
+ *   Is of type  QWebFrame.
+ */
 JavascriptInterface::JavascriptInterface(QWebFrame *parent){
 	qxtLog->debug() << "Initializing javascript interface...";
 	_parent = parent;
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * An empty destructor.
+ */
 JavascriptInterface::~JavascriptInterface() { /* destructor dummy */ }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * Attaches an instance of this class to the DOM of the HTML page.
+ *
+ * Attaches an instance of this class to the DOM of the HTML page.
+ * This enables the possibility to call slots/methods of this class in
+ * JavaScript functions of HTML page. It also calls the
+ * JavascriptInterface::loadJQuery() method.
+ *
+ * @see JavascriptInterface::loadJQuery()
+ */
 void JavascriptInterface::attachToDOM(){
 	_parent->addToJavaScriptWindowObject(QString("fbgui"), this);
 	loadJQuery();
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method load the required jQuery libraries into the HTML page.
+ *
+ * This method load the required jQuery libraries into the HTML page.
+ * The libraries are contained in the fbgui.qrc file.
+ * The Path to the files is: ":/html/js".
+ * Each library will be read and loaded into the HTML page via
+ * the evaluateJavaScript() method.
+ *
+ * @see JavascriptInterface::attachToDOM()
+ */
 void JavascriptInterface::loadJQuery(){
     QString js;
     QString pathToJsDir(DEFAULT_QRC_HTML_DIR);
@@ -49,6 +79,13 @@ void JavascriptInterface::loadJQuery(){
 //-------------------------------------------------------------------------------------------------------
 //                                Javascript functions for webpage
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method start a download.
+ *
+ * This method start a download.
+ * Can be called from inside a JavaScript function of the HTML page.
+ * Emits the JavascriptInterface::requestFile(const QString) signal.
+ */
 void JavascriptInterface::startDownload(const QString& filename){
 	// ignore if empty filename
 	if (filename.isEmpty()){
@@ -58,45 +95,117 @@ void JavascriptInterface::startDownload(const QString& filename){
 	emit requestFile(filename);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method start a download.
+ *
+ * This method start a download.
+ * Can be called from inside a JavaScript function of the HTML page.
+ *
+ * @todo add some more informations
+ */
 void JavascriptInterface::setCallbackOnFinished(const QString& function){
     qxtLog->debug() << "[jsi] Callback set: " << function;
     _callbackOnDownloadsFinished = QString(function);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method delivers system informations.
+ *
+ * This method delivers system informations. Type of informations, are defined by
+ * the parameter. The output of this method depends on the parameter.
+ * Can be called from inside a JavaScript function of the HTML page.
+ *
+ * @param infoName
+ *   Is of type QString. Defines which method will be called. Possible values are:
+ *     - mac
+ *     - ip
+ *     - mbserial
+ *     - usb
+ *
+ * @return QString
+ *   the output of the called method or "info_error" if an error occurred
+ *   (e. g. invalid parameter).
+ *
+ * @see SysInfo::getInfo(const QString& infoName)
+ */
 const QString JavascriptInterface::getSysInfo(const QString& info){
     SysInfo si;
     return si.getInfo(info);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method quits the whole program.
+ *
+ * This method quits the whole program.
+ * Can be called from inside a JavaScript function of the HTML page.
+ * Emits JavascriptInterface::quitFbgui() signal
+ */
 void JavascriptInterface::quit(){
     emit quitFbgui();
 }
 //-------------------------------------------------------------------------------------------------------
 //                            Download Manager information exchange
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method delivers some informations about the downloading file.
+ *
+ * This method delivers some informations about the downloading file.
+ *
+ * @todo add some more informations
+ */
 void JavascriptInterface::downloadInfo(const QString& filename, const double& filesize){
 	QString code = QString("downloadInfo('\%1', \%2)").arg(filename).arg(filesize);
 	_parent->evaluateJavaScript(code);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method updates the progress bar.
+ *
+ * This method updates the progress bar of the HTML page when an download
+ * happens.
+ *
+ * @todo add some more informations
+ */
 void JavascriptInterface::updateProgressBar(const int& percent, const double& speed, const QString& unit){
 	if (percent == 0) return;
 	QString code = QString("updateProgress(\%1, \%2, '\%3')").arg(percent).arg(speed).arg(unit);
 	_parent->evaluateJavaScript(code);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method sends notifications.
+ *
+ * @todo add some more informations.
+ */
 void JavascriptInterface::notify(const QString& msg){
     qxtLog->debug() << "[jsi] Notifying: " << msg;
     QString code = QString("notify('\%1')").arg(msg);
     _parent->evaluateJavaScript(code);
 }
 //-------------------------------------------------------------------------------------------------------
+/**
+ * @todo add some more informations
+ */
 void JavascriptInterface::callbackOnFinished(){
 	QString code = QString("\%1").arg(_callbackOnDownloadsFinished);
 	_parent->evaluateJavaScript(code);
 }
 //-------------------------------------------------------------------------------------------------------
 //-------------------------------------------------------------------------------------------------------
+/**
+ * This method triggers the arriving of the IP address
+ *
+ * Used for testing. This method triggers the arriving of the IP address.
+ * Not needed in the final version since the here simulated event will be
+ * fired automaticali by the udhcpc command.
+ * This methods writes some data into a specific file. This file is watched by an
+ * other process which will fire an event as soon as the file changes.
+ *
+ * @see fbgui::watchForTrigger()
+ * @see fbgui::checkForTrigger(const QString& dirname)
+ * @see bool fbgui::checkHost()
+ * @see void fbgui::loadURL()
+ */
 void JavascriptInterface::trigger(){
     QFile file(fileToTriggerURL);
     if (file.open(QIODevice::WriteOnly)){
diff --git a/src/sysinfo.cpp b/src/sysinfo.cpp
index 135db11..569fd06 100644
--- a/src/sysinfo.cpp
+++ b/src/sysinfo.cpp
@@ -2,10 +2,36 @@
 
 
 // ------------------------------------------------------------------------------------------------
+/**
+ * A empty constructor.
+ */
 SysInfo::SysInfo(){}
 // ------------------------------------------------------------------------------------------------
+/**
+ * A empty destructor.
+ */
 SysInfo::~SysInfo(){}
 // ------------------------------------------------------------------------------------------------
+/**
+ * This method returns system informations.
+ *
+ * This method returns system informations according to the parameter.
+ * This method can be called from the JavascriptInterface class with the
+ * method JavascriptInterface::getSysInfo(const QString& info).
+ *
+ * @param infoName
+ *   Is of type QString. Defines which method will be called. Possible values are:
+ *     - mac
+ *     - ip
+ *     - mbserial
+ *     - usb
+ *
+ * @return QString
+ *   the output of the called method or "info_error" if an error occurred
+ *   (e. g. invalid parameter).
+ *
+ * @see JavascriptInterface::getSysInfo(const QString& info)
+ */
 const QString SysInfo::getInfo(const QString& infoName){
 	qxtLog->debug() << "[sysinfo] requested " << infoName;
 	if (infoName == QString("mac"))
@@ -25,6 +51,21 @@ const QString SysInfo::getInfo(const QString& infoName){
 	return "info_error";
 }
 // ------------------------------------------------------------------------------------------------
+/**
+ * This method returns the clients MAC-Address.
+ *
+ * This method returns the clients MAC-Address of the "eth0" interface.
+ * The MAC-Address is used as part of the data to compute the
+ * hardwarehash of the client machine. To call this method use the
+ * SysInfo::getInfo(const QString& infoName) method with
+ * the parameter "mac"
+ *
+ * @return QString
+ *   the MAC-Address or "no_eth0" if an error occurred.
+ *
+ * @see fbgui::generatePOSTData()
+ * @see SysInfo::getInfo(const QString& infoName)
+ */
 const QString SysInfo::getMACAddress(){
 	// Returns MAC address of eth0 for now
 	QNetworkInterface qni = QNetworkInterface::interfaceFromName(QString("eth0"));
@@ -36,6 +77,19 @@ const QString SysInfo::getMACAddress(){
 	return qni.hardwareAddress();
 }
 // ------------------------------------------------------------------------------------------------
+/**
+ * This method returns the clients IP-Address.
+ *
+ * This method returns the clients IP-Address of the "eth0" interface.
+ * To call this method use the
+ * SysInfo::getInfo(const QString& infoName) method with
+ * the parameter "ip"
+ *
+ * @return QString
+ *   the IP-Address or "ip_error" if an error occurred.
+ *
+ * @see SysInfo::getInfo(const QString& infoName)
+ */
 const QString SysInfo::getIPAddress(){
 	// Again for eth0 only at the moment.
 	// TODO: this doesn't quite work yet...
@@ -52,6 +106,9 @@ const QString SysInfo::getIPAddress(){
 	return "ip_error";
 }
 // ------------------------------------------------------------------------------------------------
+/**
+ * just a test method for json.
+ */
 const QByteArray SysInfo::getNames(){
 
 	QVariantMap foo;
@@ -73,6 +130,9 @@ const QByteArray SysInfo::getNames(){
 
 }
 // ------------------------------------------------------------------------------------------------
+/**
+ * just a test method for json.
+ */
 QString SysInfo::getAllInfos(){
 	QVariantMap infos;
 	infos.insert("mac", getMACAddress());
@@ -87,6 +147,22 @@ QString SysInfo::getAllInfos(){
 	return json;
 }
 // ------------------------------------------------------------------------------------------------
+
+/**
+ * This method returns the Mainboard Serial Number.
+ *
+ * This method returns the Mainboard Serial Number. The mainboard serial
+ * number is used as part of the data to compute the hardwarehash of the
+ * client machine. To call this method use the
+ * SysInfo::getInfo(const QString& infoName) method with
+ * the parameter "mbserial"
+ *
+ * @return QString
+ *   the mainboard serial or "mainboard_serial_error" if an error occurred.
+ *
+ * @see fbgui::generatePOSTData()
+ * @see SysInfo::getInfo(const QString& infoName)
+ */
 const QString SysInfo::getMainboardSerial(){
 	QString out = "";
 	struct sysfs_class_device *class_device = sysfs_open_class_device("dmi","id");
@@ -109,6 +185,27 @@ const QString SysInfo::getMainboardSerial(){
 	return "mainboard_serial_error";
 }
 // ------------------------------------------------------------------------------------------------
+/**
+ * This method returns inforamtions about connected usb devices.
+ *
+ * This method returns the inforamtions about connected usb devices
+ * as a json formated string.
+ * Those informations are:
+ *   - the vendor
+ *   - the vendorID
+ *   - the product
+ *   - the productID
+ *   - the manufacturer
+ *   - the serial number
+ *   To call this method use the SysInfo::getInfo(const QString& infoName)
+ *   method with the parameter "usb"
+ *
+ * @return QString
+ *   all above described informations as a json formated string or "error"
+ *   if an error occurred.
+ *
+ * @see SysInfo::getInfo(const QString& infoName)
+ */
 const QString SysInfo::getUsbVendorIdProductIdSerialNumber()
 {
 	QString tag = "[sysinfo] Usb Serial:";
@@ -180,6 +277,19 @@ const QString SysInfo::getUsbVendorIdProductIdSerialNumber()
 }
 
 // ------------------------------------------------------------------------------------------------
+/**
+ * This method returns the output of the provided script.
+ *
+ * This method returns the output of the provided script.
+ * Script could be any command.
+ * This method is not used so far.
+ *
+ * @param cmd
+ *   Is of type QString. The command which will be executed
+ *
+ * @return QString
+ *   output of the script.
+ */
 QString SysInfo::getScriptOutput(QString cmd)
 {
     QProcess *process = new QProcess();