Fix documentation build on Clang-enabled QDoc

When building documentation with QDoc from Qt 5.11 or later, C++
sources are parsed by Clang. Clang expects a complete set of
include paths for resolving the types in the documented API, as
well as a module header to build a precompiled header from.

To do this, convert the /doc directory to a proper subproject
and add suitable dependencies to get the right include paths
from qmake. As QmlLive is not a Qt module, docs must also
maintain a 'dummy' module header that is passed to Clang.

Fix also remaining documentation warnings, most importantly,
the syntax of \fn commands.

Change-Id: I2e912dbc509e2bd40691463e4608081372b5d6a2
Reviewed-by: Kavindra Palaraja <kpalaraja@luxoft.com>
Reviewed-by: Svetlana Abramenkova <sabramenkova@luxoft.com>

21 files changed, 72 insertions, 47 deletions

diff --git a/doc/QmlLiveDoc b/doc/QmlLiveDoc
new file mode 100644
index 0000000..c19b528
--- /dev/null
+++ b/doc/QmlLiveDoc
@@ -0,0 +1,8 @@
+#include "logger.h"
+#include "logreceiver.h"
+#include "ipc/ipcserver.h"
+#include "ipc/ipcclient.h"
+#include "livehubengine.h"
+#include "livenodeengine.h"
+#include "remotepublisher.h"
+#include "remotereceiver.h"
diff --git a/doc/doc.pri b/doc/doc.pri
index b6dae4e..711e065 100644
--- a/doc/doc.pri
+++ b/doc/doc.pri
@@ -1,15 +1,2 @@
-build_online_docs: {
-    QMAKE_DOCS_TARGETDIR = qmllive
-    QMAKE_DOCS = $$PWD/qmllive-online.qdocconf
-} else {
-    QMAKE_DOCS = $$PWD/qmllive.qdocconf
-}
-
 CONFIG += prepare_docs
 load(qt_docs_targets)
-
-OTHER_FILES += \
-    $$PWD/*.qdocconf \
-    $$PWD/*.qdoc \
-    $$PWD/examples/*.qdoc \
-    $$PWD/images/*.png
diff --git a/doc/doc.pro b/doc/doc.pro
new file mode 100644
index 0000000..4c486dc
--- /dev/null
+++ b/doc/doc.pro
@@ -0,0 +1,19 @@
+TEMPLATE = aux
+
+CONFIG += force_qt
+QT *= quick network
+
+build_online_docs: {
+    QMAKE_DOCS_TARGETDIR = qmllive
+    QMAKE_DOCS = $$PWD/qmllive-online.qdocconf
+} else {
+    QMAKE_DOCS = $$PWD/qmllive.qdocconf
+}
+
+include(doc.pri)
+
+OTHER_FILES += \
+    $$PWD/*.qdocconf \
+    $$PWD/*.qdoc \
+    $$PWD/examples/*.qdoc \
+    $$PWD/images/*.png
diff --git a/doc/examples/contentplugin.qdoc b/doc/examples/contentplugin.qdoc
index ae5ede0..7334c6c 100644
--- a/doc/examples/contentplugin.qdoc
+++ b/doc/examples/contentplugin.qdoc
@@ -33,7 +33,7 @@
     \example contentplugin
     \title ContentPlugin Example
 
-    \brief Demonstrates how to write a Content Plugin for QmlLive
+    \brief Demonstrates how to write a Content Plugin for QmlLive.
 
     \image contentplugin-example.png Screenshot of the Plugin in Action
 
diff --git a/doc/examples/customruntime.qdoc b/doc/examples/customruntime.qdoc
index fdd2e2f..58edada 100644
--- a/doc/examples/customruntime.qdoc
+++ b/doc/examples/customruntime.qdoc
@@ -32,7 +32,7 @@
 \example customruntime
 \title Custom Runtime Example
 
-\brief Demonstrates how to create a Custom QmlLive Runtime
+\brief Demonstrates how to create a Custom QmlLive Runtime.
 
 \image customruntime-example.png Screenshot of the Custom QmlLive Runtime
 
diff --git a/doc/ipc-group.qdoc b/doc/ipc-group.qdoc
index 45463fe..7c9363f 100644
--- a/doc/ipc-group.qdoc
+++ b/doc/ipc-group.qdoc
@@ -34,8 +34,8 @@
 /*!
     \module ipc
 
-    \title IPC related classes
-    \brief A simple IPC solution for calling method on remote objects
+    \title IPC Related Classes
+    \brief A simple IPC solution for calling method on remote objects.
 
     The IPC is based on the idea to have a server with individual connections
     to clients and a client. The server is waiting for method calls from the
diff --git a/doc/qmllive-group.qdoc b/doc/qmllive-group.qdoc
index 52df782..1692595 100644
--- a/doc/qmllive-group.qdoc
+++ b/doc/qmllive-group.qdoc
@@ -35,7 +35,8 @@
     \module qmllive
 
     \title QmlLive Module
-    \brief Classes for watching a workspace and for local and remote reloading of Qt Quick user interfaces
+    \brief Classes for watching a workspace and for local and remote reloading
+           of Qt Quick user interfaces.
 
     The QmlLive module allows a developer to quickly create his own instance of
     a QmlLive workbench or a QmlLive runtime.
diff --git a/doc/qmllive-project.qdocconf b/doc/qmllive-project.qdocconf
index c23aede..6933d29 100644
--- a/doc/qmllive-project.qdocconf
+++ b/doc/qmllive-project.qdocconf
@@ -3,6 +3,9 @@ description = QmlLive Reference Documentation
 url = https://doc.qt.io/QtQmlLive
 version = $QT_VERSION
 
+moduleheader = QmlLiveDoc
+includepaths += -I ../src
+
 sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
 headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
 
@@ -37,6 +40,8 @@ qhp.QmlLive.subprojects.manual.title = Qt QmlLive
 qhp.QmlLive.subprojects.manual.indexTitle = Qt QmlLive
 qhp.QmlLive.subprojects.manual.type = manual
 
+depends = qtcore qtqml qtquick qtnetwork qtautomotivesuite
+
 navigation.homepage = "Qt Automotive Suite"
 navigation.landingpage = "Qt QmlLive"
 buildversion = "Qt QmlLive $QT_VERSION"
diff --git a/examples/examples.pro b/examples/examples.pro
index 6e28f9a..67d00d6 100644
--- a/examples/examples.pro
+++ b/examples/examples.pro
@@ -1,3 +1,4 @@
+include(../doc/doc.pri)
 TEMPLATE = subdirs
 SUBDIRS += customruntime \
            contentplugin
diff --git a/qmllive.pro b/qmllive.pro
index 9d90b03..12c7a4d 100755
--- a/qmllive.pro
+++ b/qmllive.pro
@@ -6,7 +6,6 @@ requires(!ios)
 load(configure)
 load(config-output)
 include(qmllive.pri)
-include(doc/doc.pri)
 
 !skip-bench:!minQtVersion(5, 4, 0): error("You need at least Qt 5.4.0 to build QmlLive Bench")
 !skip-tests:!minQtVersion(5, 4, 0): error("You need at least Qt 5.4.0 to build QmlLive tests")
@@ -18,6 +17,9 @@ CONFIG += ordered
 SUBDIRS += src
 !skip-tests: SUBDIRS += tests
 !skip-examples: SUBDIRS += examples
+SUBDIRS += doc
+
+include(doc/doc.pri)
 
 OTHER_FILES += \
     README.md \
diff --git a/src/ipc/ipcclient.cpp b/src/ipc/ipcclient.cpp
index 9da86ff..a256bc3 100644
--- a/src/ipc/ipcclient.cpp
+++ b/src/ipc/ipcclient.cpp
@@ -51,7 +51,7 @@ public:
 
 /*!
  * \class IpcClient
- * \brief Client to send remote calls to an IpcServer
+ * \brief Client to send remote calls to an IpcServer.
  * \inmodule ipc
  *
  * The IPC system uses the normalized signal/slot signature to
@@ -382,34 +382,33 @@ qint64 IpcClient::sendPackage(const QString &method, const QByteArray &data)
 }
 
 /*!
- * \fn void IpcClient::connected();
- * Emitted once when the connection to the server is established
+ * \fn IpcClient::connected()
+ * Emitted once when the connection to the server is established.
  */
 
 /*!
- * \fn void IpcClient::disconnected();
- * Emitted once when the connection to the server is terminated
+ * \fn IpcClient::disconnected()
+ * Emitted once when the connection to the server is terminated.
  */
 
 /*!
- * \fn void IpcClient::connectionError(QAbstractSocket::SocketError socketError);
+ * \fn IpcClient::connectionError(QAbstractSocket::SocketError socketError)
  * Emitted when an error happens when connecting or disconnecting from the server
- * \a socketError describes what error happened
+ * \a socketError describes what error happened.
  */
 
 /*!
- * \fn void IpcClient::sentSuccessfully(const QUuid& uuid);
+ * \fn IpcClient::sentSuccessfully(const QUuid& uuid)
  * Emitted when the Package identified by \a uuid was successfully sent.
  */
 
 /*!
- * \fn void IpcClient::sendingError(const QUuid& uuid, QAbstractSocket::SocketError socketError);
- * Emitted when an error happens when sending the Package identified by \a uuid.
- * \a socketError describes what error happened
+ * \fn IpcClient::sendingError(const QUuid& uuid, QAbstractSocket::SocketError socketError)
+ * Emitted when an error \a socketError occurred while sending a Package identified by \a uuid.
  */
 
 /*!
- * \fn void IpcClient::received(const QString& method, const QByteArray& content)
+ * \fn IpcClient::received(const QString& method, const QByteArray& content)
  *
- * Called when a RPC call was received. Provides the \a method and \a content
+ * Called when an RPC call was received. Provides the \a method and the \a content.
  */
diff --git a/src/livedocument.cpp b/src/livedocument.cpp
index 501ab78..3429636 100644
--- a/src/livedocument.cpp
+++ b/src/livedocument.cpp
@@ -36,7 +36,7 @@
 
 /*!
  * \class LiveDocument
- * \brief Encapsulates a relative path to a workspace document
+ * \brief Encapsulates a relative path to a workspace document.
  * \inmodule qmllive
  */
 
diff --git a/src/livehubengine.cpp b/src/livehubengine.cpp
index 342e68d..b3bd56f 100644
--- a/src/livehubengine.cpp
+++ b/src/livehubengine.cpp
@@ -41,7 +41,7 @@
 
 /*!
  * \class LiveHubEngine
- * \brief The LiveHubEngine class watches over a workspace and notifies a node on changes
+ * \brief The LiveHubEngine class watches over a workspace and notifies a node on changes.
  * \inmodule qmllive
  *
  * The live hub watches over a workspace and notifies a live node about changed files. A
diff --git a/src/logger.cpp b/src/logger.cpp
index c202607..90a0dca 100644
--- a/src/logger.cpp
+++ b/src/logger.cpp
@@ -39,7 +39,7 @@ QMutex Logger::m_mutex;
 
 /*!
  * \class Logger
- * \brief Installs a qt messageHandler and receives all log messages
+ * \brief Installs a qt messageHandler and receives all log messages.
  * \inmodule qmllive
  *
  * The intention is to use this class if you want to display the log into widget
diff --git a/src/logreceiver.cpp b/src/logreceiver.cpp
index 26a33f6..7b91b1a 100644
--- a/src/logreceiver.cpp
+++ b/src/logreceiver.cpp
@@ -37,7 +37,7 @@
 
 /*!
  * \class LogReceiver
- * \brief Connects to a port and waits for log messages sent via udp
+ * \brief Connects to a port and waits for log messages sent via UDP.
  * \inmodule qmllive
  *
  * \sa Logger, RemoteLogger
diff --git a/src/qmlhelper.cpp b/src/qmlhelper.cpp
index 0caffa9..1de9716 100644
--- a/src/qmlhelper.cpp
+++ b/src/qmlhelper.cpp
@@ -35,12 +35,12 @@
 
 /*!
  * \class QmlHelper
- * \brief Provides a set of helper functions to setup your QML viewer
+ * \brief Provides a set of helper functions to setup your QML viewer.
  * \inmodule qmllive
  */
 
 /*!
- * Standard constructor using \a parent as parent
+ * Standard constructor using \a parent as parent.
  */
 QmlHelper::QmlHelper(QObject *parent) :
     QObject(parent)
@@ -48,9 +48,10 @@ QmlHelper::QmlHelper(QObject *parent) :
 }
 
 /*!
- * Loads dummy data from a "dummydata" folder in the workspace folder
- * \a engine defines the Engine where you want to export the dummy data to
- * The "dummydata" will be searched in the "dummydata" sub directory of \a workspace
+ * Loads dummy data from a "dummydata" folder in the workspace folder.
+ * \a engine defines the Engine where you want to export the dummy data to.
+ * The "dummydata" will be searched in the "dummydata" subdirectory of \a
+ * workspace.
  */
 void QmlHelper::loadDummyData(QQmlEngine *engine, const QString &workspace)
 {
diff --git a/src/remotelogger.cpp b/src/remotelogger.cpp
index 60742ff..31ea3b8 100644
--- a/src/remotelogger.cpp
+++ b/src/remotelogger.cpp
@@ -35,7 +35,7 @@
 
 /*!
  * \class RemoteLogger
- * \brief Installs a qt messageHandler and sends the logs over udp
+ * \brief Installs a Qt messageHandler and sends the logs over UDP.
  * \inmodule qmllive
  *
  * \sa Logger, LogReceiver
@@ -53,7 +53,7 @@ RemoteLogger::RemoteLogger(QObject *parent) :
 }
 
 /*!
- * Sets the \a address where the log messages will be sent to
+ * Sets the \a address where the log messages will be sent to.
  * \sa setPort()
  */
 void RemoteLogger::setHostAddress(const QHostAddress &address)
@@ -62,7 +62,7 @@ void RemoteLogger::setHostAddress(const QHostAddress &address)
 }
 
 /*!
- * Sets the \a port where the log messages will be sent to
+ * Sets the \a port where the log messages will be sent to.
  * \sa setHostAddress()
  */
 void RemoteLogger::setPort(int port)
@@ -88,7 +88,7 @@ void RemoteLogger::broadcast(int type, const QString &msg, const QUrl &url, int
 }
 
 /*!
- * Broadcasts each error from the \a errors
+ * Broadcasts each error from the \a errors.
  */
 void RemoteLogger::appendToLog(const QList<QQmlError> &errors)
 {
diff --git a/src/remotepublisher.cpp b/src/remotepublisher.cpp
index 2a9a63e..5984dae 100644
--- a/src/remotepublisher.cpp
+++ b/src/remotepublisher.cpp
@@ -43,7 +43,7 @@
 
 /*!
  * \class RemotePublisher
- * \brief Publishes hub changes to a remote node
+ * \brief Publishes hub changes to a remote node.
  * \inmodule qmllive
  *
  * To see the progress which commands were really sent successfully to to the server
diff --git a/src/remotereceiver.cpp b/src/remotereceiver.cpp
index 706394e..0cd707e 100644
--- a/src/remotereceiver.cpp
+++ b/src/remotereceiver.cpp
@@ -46,7 +46,7 @@
 
 /*!
  * \class RemoteReceiver
- * \brief Receives commands form the remote publisher
+ * \brief Receives commands from the remote publisher.
  * \inmodule qmllive
  *
  * Receives commands from a remote publisher to publish workspace files and to
diff --git a/src/src.pro b/src/src.pro
index b18eb1c..625733e 100644
--- a/src/src.pro
+++ b/src/src.pro
@@ -1,4 +1,5 @@
 include(../qmllive.pri)
+include(../doc/doc.pri)
 
 TEMPLATE = subdirs
 CONFIG += ordered
diff --git a/tests/tests.pro b/tests/tests.pro
index 3179cdf..332d12f 100644
--- a/tests/tests.pro
+++ b/tests/tests.pro
@@ -1,3 +1,4 @@
+include(../doc/doc.pri)
 TEMPLATE = subdirs