add doxygen documentation

README.md

@@ -60,8 +60,9 @@ Dependencies
 
 ### Optional dependencies ###
 
-* qt5-network (if Qt5 is used) (*requires for GitHub module*)
+* qt5-network (if Qt5 is used) *(requires for GitHub module)*
-* qt5-webkit (if Qt5 is used) or qtwebkit (if Qt4 is used) (*requires for GitReport module*)
+* qt5-webkit (if Qt5 is used) or qtwebkit (if Qt4 is used) *(requires for GitReport module)*
+* doxygen *(developers documentation)*
 
 ### Make dependencies ###
 
@@ -101,7 +102,7 @@ Installation
 ### Available cmake flags ###
 
 * `-DBUILD_AS_LIBRARY:BOOL=0` - build the application but not a shared library
-* `-DBUILD_DOCS:BOOL=0` - do not build developer documentation
+* `-DBUILD_DOCS:BOOL=1` - build developer documentation
 * `-DENABLE_GITHUB=0` - disable GitHub module
 * `-DENABLE_GITREPORT=0` - disable GitReport module
 * `-DUSE_QT5:BOOL=0` - use Qt4 instead of Qt5 for GUI

sources/CMakeLists.txt

@@ -25,6 +25,7 @@ message (STATUS "Build date: ${CURRENT_DATE}")
 # install options
 option (USE_QT5 "Use Qt5 instead of Qt4" ON)
 option (BUILD_AS_LIBRARY "Build the application as a shared library" ON)
+option (BUILD_DOCS "Build developers documentation" OFF)
 option (ENABLE_GITHUB "Enable GitHub module" ON)
 option (ENABLE_GITREPORT "Enable GitReport module" ON)
 
@@ -53,6 +54,9 @@ set (HEADERS "")
 
 add_subdirectory (${SUBPROJECT_SOURCE_DIR})
 
+if (BUILD_DOCS)
+    include (docs.cmake)
+endif ()
 if (NOT BUILD_AS_LIBRARY)
     install (FILES ${SUBPROJECT}.desktop DESTINATION share/applications/)
 endif ()

sources/docs.cmake

@@ -0,0 +1,21 @@
+# include files
+install (FILES ${HEADERS} DESTINATION include/${SUBPROJECT})
+
+# doxygen documentation
+find_package (Doxygen)
+if (NOT DOXYGEN_FOUND)
+    message (STATUS "WARNING: Doxygen not found - Reference manual will not be created")
+    return ()
+endif ()
+
+configure_file (doxygen.conf.in ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf)
+add_custom_target (oxygen-docs ALL COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf)
+
+# man pages
+# workaround for man pages
+set (MAN_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/man/man3)
+install (FILES ${MAN_DIR}/Reportabug.3 DESTINATION share/man/man3 RENAME ${SUBPROJECT}_Reportabug.3)
+install (FILES ${MAN_DIR}/GithubModule.3 DESTINATION share/man/man3 RENAME ${SUBPROJECT}_GithubModule.3)
+install (FILES ${MAN_DIR}/GitreportModule.3 DESTINATION share/man/man3 RENAME ${SUBPROJECT}_GitreportModule.3)
+# html docs
+install (DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs/html DESTINATION share/doc/${SUBPROJECT})

sources/src/githubmodule.cpp

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file githubmodule.cpp
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #include "githubmodule.h"
 #include "reportabug.h"
@@ -31,6 +38,12 @@
 #include "config.h"
 
 
+/**
+ * @class GithubModule
+ */
+/**
+ * @fn GithubModule
+ */
 GithubModule::GithubModule(QWidget *parent, bool debugCmd)
     : QObject(parent),
       debug(debugCmd),
@@ -39,12 +52,18 @@ GithubModule::GithubModule(QWidget *parent, bool debugCmd)
 }
 
 
+/**
+ * @fn ~GithubModule
+ */
 GithubModule::~GithubModule()
 {
     if (debug) qDebug() << "[GithubModule]" << "[~GithubModule]";
 }
 
 
+/**
+ * @fn prepareRequest
+ */
 QByteArray GithubModule::prepareRequest(const QString title, const QString body)
 {
     if (debug) qDebug() << "[GithubModule]" << "[prepareRequest]";
@@ -76,6 +95,9 @@ QByteArray GithubModule::prepareRequest(const QString title, const QString body)
 }
 
 
+/**
+ * @fn parseString
+ */
 QString GithubModule::parseString(QString line)
 {
     if (debug) qDebug() << "[GithubModule]" << "[parseString]";
@@ -94,6 +116,9 @@ QString GithubModule::parseString(QString line)
 }
 
 
+/**
+ * @fn sendReportUsingGithub
+ */
 void GithubModule::sendReportUsingGithub(const QMap<QString, QString> info)
 {
     if (debug) qDebug() << "[GithubModule]" << "[sendReportUsingGithub]";
@@ -120,6 +145,9 @@ void GithubModule::sendReportUsingGithub(const QMap<QString, QString> info)
 }
 
 
+/**
+ * @fn githubFinished
+ */
 void GithubModule::githubFinished(QNetworkReply *reply)
 {
     if (debug) qDebug() << "[GithubModule]" << "[githubFinished]";

sources/src/githubmodule.h

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file githubmodule.h
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #ifndef GITHUBMODULE_H
 #define GITHUBMODULE_H
@@ -25,25 +32,73 @@
 class Reportabug;
 class QNetworkReply;
 
+/**
+ * @brief The GithubModule class creates issue over GitHub.
+ * @details The GitHub API is used for creating issue. Please visit
+ * [the API page](https://developer.github.com/v3/issues/) for more details.
+ * This module requires an users authentication. The typical POST request is:
+ * @code
+ * curl -X POST -u user:pass -d '{"title":"A new bug","body":"Some error occurs"}' https://api.github.com/repos/owner/repo/issues
+ * @endcode
+ *
+ * This module depends on QtNetwork module.
+ */
 class GithubModule : public QObject
 {
     Q_OBJECT
 
 public:
+    /**
+     * @brief GithubModule class constructor
+     * @param parent         parent object
+     * @param debugCmd       show debug messages
+     */
     explicit GithubModule(QWidget *parent = 0,
                           bool debugCmd = false);
+    /**
+     * @brief GithubModule class destructor
+     */
     ~GithubModule();
 
 public slots:
+    /**
+     * @brief method which creates an issue
+     * @param info           issue details. Needed keys are:
+     *                       body (body of an issue),
+     *                       password (GitHub password),
+     *                       title (title of an issue),
+     *                       username (GitHub user name),
+     */
     void sendReportUsingGithub(const QMap<QString, QString> info);
 
 private slots:
+    /**
+     * @brief method which will be called after sending POST request
+     * @param reply          reply of the request
+     */
     void githubFinished(QNetworkReply *reply);
 
 private:
+    /**
+     * @brief show debug messages
+     */
     bool debug;
+    /**
+     * @brief Reportabug class
+     */
     Reportabug *mainWindow;
+    /**
+     * @brief method which parses string and replace known tags
+     * @param line           source line
+     * @return replaced line
+     */
     QString parseString(QString line);
+    /**
+     * @brief method which prepares raw issue details for sending request
+     * @param title          title of an issue
+     * @param body           body of an issue
+     * @return JSON string
+     */
     QByteArray prepareRequest(const QString title, const QString body);
 };
 

sources/src/gitreportmodule.cpp

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file gitreportmodule.cpp
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #include "gitreportmodule.h"
 #include "reportabug.h"
@@ -30,6 +37,12 @@
 #include "config.h"
 
 
+/**
+ * @class GitreportModule
+ */
+/**
+ * @fn GitreportModule
+ */
 GitreportModule::GitreportModule(QWidget *parent, bool debugCmd)
     : QObject(parent),
       debug(debugCmd),
@@ -39,6 +52,9 @@ GitreportModule::GitreportModule(QWidget *parent, bool debugCmd)
 }
 
 
+/**
+ * @fn ~GitreportModule
+ */
 GitreportModule::~GitreportModule()
 {
     if (debug) qDebug() << "[GitreportModule]" << "[~GitreportModule]";
@@ -47,6 +63,9 @@ GitreportModule::~GitreportModule()
 }
 
 
+/**
+ * @fn sendReportUsingGitreport
+ */
 void GitreportModule::sendReportUsingGitreport(const QMap<QString, QString> info)
 {
     if (debug) qDebug() << "[GitreportModule]" << "[sendReportUsingGitreport]";
@@ -78,6 +97,9 @@ void GitreportModule::sendReportUsingGitreport(const QMap<QString, QString> info
 }
 
 
+/**
+ * @fn gitreportLoaded
+ */
 void GitreportModule::gitreportLoaded(const bool state)
 {
     if (debug) qDebug() << "[GitreportModule]" << "[gitreportLoaded]";
@@ -100,6 +122,9 @@ void GitreportModule::gitreportLoaded(const bool state)
 }
 
 
+/**
+ * @fn gitreportFinished
+ */
 void GitreportModule::gitreportFinished(const bool state)
 {
     if (debug) qDebug() << "[GitreportModule]" << "[gitreportFinished]";

sources/src/gitreportmodule.h

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file gitreportmodule.h
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #ifndef GITREPORTMODULE_H
 #define GITREPORTMODULE_H
@@ -24,26 +31,66 @@
 
 class Reportabug;
 
+/**
+ * @brief The GitreportModule class creates issue over GitReports
+ * @details This module uses [GitReport](https://gitreports.com/about) for
+ * creating an issue. Please visit [this page](https://gitreports.com/)
+ * and set up it for your repository.
+ *
+ * This module depends on QtWebKit module.
+ */
 class GitreportModule : public QObject
 {
     Q_OBJECT
 
 public:
+    /**
+     * @brief GitreportModule class constructor
+     * @param parent         parent object
+     * @param debugCmd       show debug messages
+     */
     explicit GitreportModule(QWidget *parent = 0,
                              bool debugCmd = false);
+    /**
+     * @brief GitreportModule class destructor
+     */
     ~GitreportModule();
+    /**
+     * @brief Webkit item which is used for loading web page
+     */
     QWebView *webView;
 
 public slots:
+    /**
+     * @brief method which creates an issue
+     * @param info           issue details. Needed keys are:
+     *                       body (body of an issue)
+     *                       password (user email),
+     *                       username (user name),
+     */
     void sendReportUsingGitreport(const QMap<QString, QString> info);
 
 private slots:
+    /**
+     * @brief method which will be called after sending request
+     * @param bool           state of web page loading
+     */
     void gitreportFinished(const bool state);
+    /**
+     * @brief method which will be called after loading of web page
+     * @param bool           state of web page loading
+     */
     void gitreportLoaded(const bool state);
 
 private:
+    /**
+     * @brief show debug messages
+     */
     bool debug;
-    Reportabug *mainWindow;
+    /**
+     * @brief Reportabug class
+     */
+    Reportabug *mainWindow;;
 };
 
 

sources/src/main.cpp

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file main.cpp
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 
 #include <QApplication>
@@ -21,8 +28,13 @@
 #include "reportabug.h"
 #include "version.h"
 
-
+/**
+ * @fn main
+ */
 int main(int argc, char *argv[])
+/**
+ * @return QApplication.exec()
+ */
 {
     QApplication a(argc, argv);
 

sources/src/reportabug.cpp

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file reportabug.cpp
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #include "reportabug.h"
 #include "ui_reportabug.h"
@@ -31,6 +38,12 @@
 #include "version.h"
 
 
+/**
+ * @class Reportabug
+ */
+/**
+ * @fn Reportabug
+ */
 Reportabug::Reportabug(QWidget *parent, bool debugCmd)
     : QMainWindow(parent),
       debug(debugCmd),
@@ -43,6 +56,9 @@ Reportabug::Reportabug(QWidget *parent, bool debugCmd)
 }
 
 
+/**
+ * @fn ~Reportabug
+ */
 Reportabug::~Reportabug()
 {
     if (debug) qDebug() << "[Reportabug]" << "[~Reportabug]";
@@ -57,6 +73,9 @@ Reportabug::~Reportabug()
 }
 
 
+/**
+ * @fn externalUpdateTab
+ */
 void Reportabug::externalUpdateTab()
 {
     if (debug) qDebug() << "[Reportabug]" << "[externalUpdateTab]";
@@ -65,6 +84,9 @@ void Reportabug::externalUpdateTab()
 }
 
 
+/**
+ * @fn createActions
+ */
 void Reportabug::createActions()
 {
     if (debug) qDebug() << "[Reportabug]" << "[createActions]";
@@ -75,6 +97,9 @@ void Reportabug::createActions()
 }
 
 
+/**
+ * @fn createComboBox
+ */
 void Reportabug::createComboBox()
 {
     if (debug) qDebug() << "[Reportabug]" << "[createComboBox]";
@@ -87,6 +112,9 @@ void Reportabug::createComboBox()
 }
 
 
+/**
+ * @fn getNumberByIndex
+ */
 int Reportabug::getNumberByIndex(const int index)
 {
     if (debug) qDebug() << "[Reportabug]" << "[getNumberByIndex]";
@@ -110,6 +138,9 @@ int Reportabug::getNumberByIndex(const int index)
 }
 
 
+/**
+ * @fn initModules
+ */
 void Reportabug::initModules()
 {
     if (debug) qDebug() << "[Reportabug]" << "[initModules]";
@@ -130,6 +161,9 @@ void Reportabug::initModules()
 }
 
 
+/**
+ * @fn keyPressEvent
+ */
 void Reportabug::keyPressEvent(QKeyEvent *pressedKey)
 {
     if (debug) qDebug() << "[Reportabug]" << "[keyPressEvent]";
@@ -139,6 +173,9 @@ void Reportabug::keyPressEvent(QKeyEvent *pressedKey)
 }
 
 
+/**
+ * @fn parseString
+ */
 QString Reportabug::parseString(QString line)
 {
     if (debug) qDebug() << "[Reportabug]" << "[parseString]";
@@ -157,6 +194,9 @@ QString Reportabug::parseString(QString line)
 }
 
 
+/**
+ * @fn sendReport
+ */
 void Reportabug::sendReport()
 {
     if (debug) qDebug() << "[Reportabug]" << "[sendReport]";
@@ -181,6 +221,9 @@ void Reportabug::sendReport()
 }
 
 
+/**
+ * @fn showWindow
+ */
 void Reportabug::showWindow()
 {
     externalUpdateTab();
@@ -188,6 +231,9 @@ void Reportabug::showWindow()
 }
 
 
+/**
+ * @fn updateTabs
+ */
 void Reportabug::updateTabs(const int index)
 {
     if (debug) qDebug() << "[Reportabug]" << "[updateTabs]";

sources/src/reportabug.h

@@ -14,6 +14,13 @@
  * You should have received a copy of the GNU Lesser General Public        *
  * License along with this library.                                        *
  ***************************************************************************/
+/**
+ * @file reportabug.h
+ * Source code of reportabug
+ * @author Evgeniy Alekseev
+ * @copyright LGPLv3
+ * @bug https://github.com/arcan1s/reportabug/issues
+ */
 
 #ifndef REPORTABUG_H
 #define REPORTABUG_H
@@ -30,33 +37,97 @@ namespace Ui {
 class Reportabug;
 }
 
+/**
+ * @brief The Reportabug class is a main class of the application
+ */
 class Reportabug : public QMainWindow
 {
     Q_OBJECT
 
 public:
+    /**
+     * @brief Reportabug class constructor
+     * @param parent         parent object
+     * @param debugCmd       show debug messages
+     */
     explicit Reportabug(QWidget *parent = 0,
                         bool debugCmd = false);
+    /**
+     * @brief Reportabug class destructor
+     */
     ~Reportabug();
+    /**
+     * @brief method which is used for update tabs from external classes
+     */
     void externalUpdateTab();
 
 public slots:
+    /**
+     * @brief method which creates an issue
+     */
     void sendReport();
+    /**
+     * @brief method which updates text and shows window
+     */
     void showWindow();
+    /**
+     * @brief method which updates text
+     * @param index          the current combobox index
+     */
     void updateTabs(const int index);
 
 private:
+    /**
+     * @brief show debug messages
+     */
     bool debug;
+    /**
+     * @brief contains information about enabled modules
+     */
     bool modules[2];
+    /**
+     * @brief class user interface
+     */
     Ui::Reportabug *ui;
     // modules
+    /**
+     * @brief GitHub module
+     */
     GithubModule *github;
+    /**
+     * @brief GitReports module
+     */
     GitreportModule *gitreport;
+    /**
+     * @brief method which creates the window actions
+     */
     void createActions();
+    /**
+     * @brief method which adds a text into combobox
+     */
     void createComboBox();
+    /**
+     * @brief method which parses combobox content
+     * @param index          the current combobox index
+     * @return -1 if there is no any selected modules
+     * @return 0 if the GitHub module is selected
+     * @return 1 if the GitReports module is selected
+     */
     int getNumberByIndex(const int index);
+    /**
+     * @brief method which initializates modules
+     */
     void initModules();
+    /**
+     * @brief method which monitors on pressed keys
+     * @param pressedKey     the current pressed key
+     */
     void keyPressEvent(QKeyEvent *pressedKey);
+    /**
+     * @brief method which parses string and replace known tags
+     * @param line           source line
+     * @return replaced line
+     */
     QString parseString(QString line);
 };