From 52f075659797b5f1d559e471153498507d3f33a7 Mon Sep 17 00:00:00 2001
From: Klaus Basan <klaus.basan@klausbasan.de>
Date: Wed, 2 Mar 2016 23:36:06 +0100
Subject: [PATCH] refs #485, refs #608 Doxygen improvements/fixes

---
 docs/Doxyfile.qmake             |  2 +-
 src/blackgui/blackgui.h         | 46 +++++++++++++++++++++++++++++++++
 src/blackmisc/blackmiscexport.h | 12 ++++++---
 src/swiftcore/main.cpp          |  2 ++
 src/swiftcore/swiftcore.h       |  8 +++---
 src/swiftguistandard/main.cpp   |  2 ++
 6 files changed, 65 insertions(+), 7 deletions(-)
 create mode 100644 src/blackgui/blackgui.h

diff --git a/docs/Doxyfile.qmake b/docs/Doxyfile.qmake
index f26e11e74..de8271bac 100644
--- a/docs/Doxyfile.qmake
+++ b/docs/Doxyfile.qmake
@@ -836,7 +836,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = $(DOXY_SRC_ROOT)/src
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
diff --git a/src/blackgui/blackgui.h b/src/blackgui/blackgui.h
new file mode 100644
index 000000000..b0a811466
--- /dev/null
+++ b/src/blackgui/blackgui.h
@@ -0,0 +1,46 @@
+/* Copyright (C) 2016
+ * swift Project Community / Contributors
+ *
+ * This file is part of swift project. It is subject to the license terms in the LICENSE file found in the top-level
+ * directory of this distribution and at http://www.swift-project.org/license.html. No part of swift project,
+ * including this file, may be copied, modified, propagated, or distributed except according to the terms
+ * contained in the LICENSE file.
+ */
+
+#ifndef BLACKGUI_NAMESPACES_H
+#define BLACKGUI_NAMESPACES_H
+
+// just a dummy header, namespace documentation will go here
+//! \file
+
+/*!
+ * \namespace BlackGui
+ * \brief GUI related classes.
+ */
+
+/*!
+ * \namespace BlackGui::Components
+ * \brief High level reusable GUI components.
+ */
+
+/*!
+ * \namespace BlackGui::Filters
+ * \brief Filter to search data sets.
+ */
+
+/*!
+ * \namespace BlackGui::Models
+ * \brief Models to be used with views, mainly QTableView
+ */
+
+/*!
+ * \namespace BlackGui::Views
+ * \brief Views, mainly QTableView
+ */
+
+/*!
+ * \namespace BlackGui::Win
+ * \brief Windows specific classes.
+ */
+
+#endif
diff --git a/src/blackmisc/blackmiscexport.h b/src/blackmisc/blackmiscexport.h
index 6cfa8a5f4..08c5b16a7 100644
--- a/src/blackmisc/blackmiscexport.h
+++ b/src/blackmisc/blackmiscexport.h
@@ -18,7 +18,6 @@
  * \def BLACKMISC_EXPORT
  * BlackMisc Export Macro
  */
-
 #ifndef WITH_STATIC
 #  if defined(BUILD_BLACKMISC_LIB)
 #    define BLACKMISC_EXPORT Q_DECL_EXPORT
@@ -33,15 +32,22 @@
  * \def BLACKMISC_EXPORT_TEMPLATE
  * BlackMisc Template Export Macro
  */
-
 #if defined(Q_OS_WIN) && defined(Q_CC_GNU)
 #  define BLACKMISC_EXPORT_TEMPLATE BLACKMISC_EXPORT
 #else
 #  define BLACKMISC_EXPORT_TEMPLATE
 #endif
 
-//! make a define quoted (normally to be used then with QString)
+
+//! \cond
+// helper define
 #define BLACK_STRINGIFY_X(v) #v
+//! \endcond
+
+/*!
+ * \def BLACK_STRINGIFY
+ * Value in quotes (normally to be used then with QString)
+ */
 #define BLACK_STRINGIFY(v) BLACK_STRINGIFY_X(v)
 
 #endif // guard
diff --git a/src/swiftcore/main.cpp b/src/swiftcore/main.cpp
index 8f1fe032a..f65aacbc3 100644
--- a/src/swiftcore/main.cpp
+++ b/src/swiftcore/main.cpp
@@ -26,6 +26,7 @@ using namespace BlackGui;
 
 int main(int argc, char *argv[])
 {
+    //! [CSwiftGuiStdApplication]
     QApplication qa(argc, argv);
     CGuiApplication a("swift core", CIcons::swiftNova24());
     a.addWindowStateOption();
@@ -40,6 +41,7 @@ int main(int argc, char *argv[])
                   CCoreFacadeConfig::forCoreAllLocalInDBus(dBusAdress) :
                   CCoreFacadeConfig::forCoreAllLocalInDBusNoAudio(dBusAdress));
     a.start();
+    //! [CSwiftGuiStdApplication]
 
     if (!QSystemTrayIcon::isSystemTrayAvailable())
     {
diff --git a/src/swiftcore/swiftcore.h b/src/swiftcore/swiftcore.h
index 234627f39..70c8dd814 100644
--- a/src/swiftcore/swiftcore.h
+++ b/src/swiftcore/swiftcore.h
@@ -22,7 +22,9 @@
 
 namespace Ui { class CSwiftCore; }
 
-//! swift core control
+/*!
+ * swift core control GUI
+ */
 class CSwiftCore :
     public BlackGui::CSystemTrayWindow,
     public BlackGui::IMainWindowAccess,
@@ -44,7 +46,7 @@ private slots:
     void ps_stopCorePressed();
     void ps_appendLogMessage(const BlackMisc::CStatusMessage &message);
     void ps_p2pModeToggled(bool checked);
-    //! }@
+    //! @}
 
     //! Style sheet has changed
     virtual void ps_onStyleSheetsChanged();
@@ -56,7 +58,7 @@ private:
     void initLogDisplay();
     void initStyleSheet();
     void initDBusMode();
-    //! }@
+    //! @}
 
     void startCore(const QString &dBusAdress);
     void stopCore();
diff --git a/src/swiftguistandard/main.cpp b/src/swiftguistandard/main.cpp
index 889aa0b7d..6dd74001a 100644
--- a/src/swiftguistandard/main.cpp
+++ b/src/swiftguistandard/main.cpp
@@ -22,9 +22,11 @@ using namespace BlackCore;
 
 int main(int argc, char *argv[])
 {
+    //! [CSwiftGuiStdApplication]
     QApplication qa(argc, argv);
     CSwiftGuiStdApplication a;
     if (!a.start()) { return EXIT_FAILURE; }
+    //! [CSwiftGuiStdApplication]
 
     // show window
     CEnableForFramelessWindow::WindowMode windowMode = a.getWindowMode();