Doc: Resolve documentation warnings

Provide a custom module headers and additional include paths to make
Clang parse the C++ documentation correctly. This is needed as
e.g. on Linux, the build system doesn't provide these because the
module is not going to be built on that platform.

Change-Id: Id81c4dbdd546b2dea08d30ebea2717157b6df81c
Reviewed-by: Martin Smith <martin.smith@qt.io>

6 files changed, 88 insertions, 24 deletions

diff --git a/src/activeqt/container/qaxbase.h b/src/activeqt/container/qaxbase.h
index 722b210..78203f7 100644
--- a/src/activeqt/container/qaxbase.h
+++ b/src/activeqt/container/qaxbase.h
@@ -121,7 +121,7 @@ public:
 
     QVariant asVariant() const;
 
-#ifdef qdoc
+#ifdef Q_QDOC
 Q_SIGNALS:
     void signal(const QString&,int,void*);
     void propertyChanged(const QString&);
diff --git a/src/activeqt/container/qaxscript.cpp b/src/activeqt/container/qaxscript.cpp
index 7c3d497..e2768d0 100644
--- a/src/activeqt/container/qaxscript.cpp
+++ b/src/activeqt/container/qaxscript.cpp
@@ -417,6 +417,8 @@ HRESULT WINAPI QAxScriptSite::EnableModeless(BOOL fEnable)
 */
 
 /*!
+    \fn QAxScriptEngine::QAxScriptEngine(const QString &language, QAxScript *script)
+
     Constructs a QAxScriptEngine object interpreting script code in \a language
     provided by the code in \a script. This is usually done by the QAxScript
     class when \link QAxScript::load() loading a script\endlink.
@@ -440,6 +442,7 @@ QAxScriptEngine::QAxScriptEngine(const QString &language, QAxScript *script)
 }
 
 /*!
+    \fn QAxScriptEngine::~QAxScriptEngine()
     Destroys the QAxScriptEngine object, releasing all allocated
     resources.
 */
@@ -461,6 +464,7 @@ QAxScriptEngine::~QAxScriptEngine()
 */
 
 /*!
+    \fn bool QAxScriptEngine::initialize(IUnknown **ptr)
     \reimp
 */
 bool QAxScriptEngine::initialize(IUnknown **ptr)
@@ -537,6 +541,7 @@ bool QAxScriptEngine::initialize(IUnknown **ptr)
 */
 
 /*!
+    \fn bool QAxScriptEngine::hasIntrospection() const
     Returns true if the script engine supports introspection;
     otherwise returns false.
 */
@@ -557,6 +562,7 @@ bool QAxScriptEngine::hasIntrospection() const
 }
 
 /*!
+    \fn long QAxScriptEngine::queryInterface(const QUuid &uuid, void **iface) const
     Requests the interface \a uuid from the script engine object and
     sets the value of \a iface to the provided interface, or to 0 if
     the requested interface could not be provided.
@@ -580,6 +586,7 @@ long QAxScriptEngine::queryInterface(const QUuid &uuid, void **iface) const
 }
 
 /*!
+    \fn QAxScriptEngine::State QAxScriptEngine::state() const
     Returns the state of the script engine.
 */
 QAxScriptEngine::State QAxScriptEngine::state() const
@@ -597,6 +604,7 @@ QAxScriptEngine::State QAxScriptEngine::state() const
 }
 
 /*!
+    \fn void QAxScriptEngine::setState(State st)
     Sets the state of the script engine to \a st.
     Calling this function is usually not necessary.
 */
@@ -613,6 +621,7 @@ void QAxScriptEngine::setState(State st)
 }
 
 /*!
+    \fn void QAxScriptEngine::addItem(const QString &name)
     Registers an item with the script engine. Script code can
     refer to this item using \a name.
 */
@@ -659,6 +668,8 @@ void QAxScriptEngine::addItem(const QString &name)
 */
 
 /*!
+    \fn QAxScript::QAxScript(const QString &name, QAxScriptManager *manager)
+
     Constructs a QAxScript object called \a name and registers
     it with the QAxScriptManager \a manager. This is usually done by the
     QAxScriptManager class when \link QAxScriptManager::load() loading a
@@ -686,6 +697,8 @@ script_engine(0)
 }
 
 /*!
+    \fn QAxScript::~QAxScript()
+
     Destroys the object, releasing all allocated resources.
 */
 QAxScript::~QAxScript()
@@ -699,6 +712,8 @@ QAxScript::~QAxScript()
 }
 
 /*!
+    \fn bool QAxScript::load(const QString &code, const QString &language)
+
     Loads the script source \a code written in language \a language
     into the script engine. Returns true if \a code was successfully
     entered into the script engine; otherwise returns false.
@@ -741,6 +756,8 @@ bool QAxScript::load(const QString &code, const QString &language)
 }
 
 /*!
+    \fn QStringList QAxScript::functions(FunctionFlags flags) const
+
     Returns a list of all the functions in this script if the respective
     script engine supports introspection; otherwise returns an empty list.
     The functions are either provided with full prototypes or only as
@@ -771,6 +788,8 @@ QStringList QAxScript::functions(FunctionFlags flags) const
 }
 
 /*!
+    \fn QVariant QAxScript::call(const QString &function, const QVariant &var1, const QVariant &var2, const QVariant &var3, const QVariant &var4, const QVariant &var5, const QVariant &var6, const QVariant &var7, const QVariant &var8)
+
     Calls \a function, passing the parameters \a var1, \a var1,
     \a var2, \a var3, \a var4, \a var5, \a var6, \a var7 and \a var8
     as arguments and returns the value returned by the function, or an
@@ -794,6 +813,7 @@ QVariant QAxScript::call(const QString &function, const QVariant &var1,
 }
 
 /*!
+    \fn QVariant QAxScript::call(const QString &function, QList<QVariant> &arguments)
     \overload
 
     Calls \a function passing \a arguments as parameters, and returns
@@ -918,6 +938,8 @@ QAxBase *QAxScript::findObject(const QString &name)
 */
 
 /*!
+    \fn QAxScriptManager::QAxScriptManager(QObject *parent)
+
     Creates a QAxScriptManager object. \a parent is passed on to the
     QObject constructor.
 
@@ -931,6 +953,8 @@ QAxScriptManager::QAxScriptManager(QObject *parent)
 }
 
 /*!
+    \fn QAxScriptManager::~QAxScriptManager()
+
     Destroys the objects, releasing all allocated resources.
 */
 QAxScriptManager::~QAxScriptManager()
@@ -939,6 +963,8 @@ QAxScriptManager::~QAxScriptManager()
 }
 
 /*!
+    \fn QStringList QAxScriptManager::functions(QAxScript::FunctionFlags flags) const
+
     Returns a list with all the functions that are available.
     Functions provided by script engines that don't support
     introspection are not included in the list.
@@ -955,6 +981,8 @@ QStringList QAxScriptManager::functions(QAxScript::FunctionFlags flags) const
 }
 
 /*!
+    \fn QStringList QAxScriptManager::scriptNames() const
+
     Returns a list with the names of all the scripts.
 */
 QStringList QAxScriptManager::scriptNames() const
@@ -963,6 +991,8 @@ QStringList QAxScriptManager::scriptNames() const
 }
 
 /*!
+    \fn QAxScript *QAxScriptManager::script(const QString &name) const
+
     Returns the script called \a name.
 
     You can use the returned pointer to call functions directly
@@ -975,6 +1005,8 @@ QAxScript *QAxScriptManager::script(const QString &name) const
 }
 
 /*!
+    \fn void QAxScriptManager::addObject(QAxBase *object)
+
     Adds \a object to the manager. Scripts handled by this manager
     can access the object in the code using the object's
     \l{QObject::objectName}{objectName} property.
@@ -1002,6 +1034,8 @@ void QAxScriptManager::addObject(QAxBase *object)
 */
 
 /*!
+    \fn QAxScript *QAxScriptManager::load(const QString &code, const QString &name, const QString &language)
+
     Loads the script source \a code using the script engine for \a
     language. The script can later be referred to using its \a name
     which should not be empty.
@@ -1035,6 +1069,7 @@ QAxScript *QAxScriptManager::load(const QString &code, const QString &name, cons
 }
 
 /*!
+    \fn QAxScript *QAxScriptManager::load(const QString &file, const QString &name)
     \overload
 
     Loads the source code from the \a file. The script can later be
@@ -1085,6 +1120,8 @@ QAxScript *QAxScriptManager::load(const QString &file, const QString &name)
 }
 
 /*!
+    \fn QVariant QAxScriptManager::call(const QString &function, const QVariant &var1, const QVariant &var2, const QVariant &var3, const QVariant &var4, const QVariant &var5, const QVariant &var6, const QVariant &var7, const QVariant &var8)
+
     Calls \a function, passing the parameters \a var1, \a var1,
     \a var2, \a var3, \a var4, \a var5, \a var6, \a var7 and \a var8
     as arguments and returns the value returned by the function, or an
@@ -1131,7 +1168,9 @@ QVariant QAxScriptManager::call(const QString &function, const QVariant &var1,
     return s->call(function, var1, var2, var3, var4, var5, var6, var7, var8);
 }
 
-/*! \overload
+/*!
+    \fn QVariant QAxScriptManager::call(const QString &function, QList<QVariant> &arguments)
+    \overload
 
     Calls \a function passing \a arguments as parameters, and returns
     the result. Returns when the script's execution has finished.
@@ -1152,6 +1191,7 @@ QVariant QAxScriptManager::call(const QString &function, QList<QVariant> &argume
 }
 
 /*!
+    \fn bool QAxScriptManager::registerEngine(const QString &name, const QString &extension, const QString &code)
     Registers the script engine called \a name and returns true if the
     engine was found; otherwise does nothing and returns false.
 
@@ -1179,6 +1219,8 @@ bool QAxScriptManager::registerEngine(const QString &name, const QString &extens
 }
 
 /*!
+    \fn QString QAxScriptManager::scriptFileFilter()
+
     Returns a file filter listing all the supported script languages.
     This filter string is convenient for use with QFileDialog.
 */
@@ -1215,6 +1257,7 @@ QString QAxScriptManager::scriptFileFilter()
 */
 
 /*!
+    \fn QAxScript *QAxScriptManager::scriptForFunction(const QString &function) const
     \internal
 
     Returns a pointer to the first QAxScript that knows
diff --git a/src/activeqt/control/qaxserverbase.cpp b/src/activeqt/control/qaxserverbase.cpp
index d46ddda..22eb6b4 100644
--- a/src/activeqt/control/qaxserverbase.cpp
+++ b/src/activeqt/control/qaxserverbase.cpp
@@ -1040,7 +1040,7 @@ HRESULT GetClassObject(REFIID clsid, REFIID iid, void **ppUnk)
 }
 
 
-/*!
+/*! \internal
     Constructs a QAxServerBase object wrapping the QWidget \a
     classname into an ActiveX control.
 
@@ -1058,7 +1058,7 @@ QAxServerBase::QAxServerBase(const QString &classname, IUnknown *outerUnknown)
     internalCreate();
 }
 
-/*!
+/*! \internal
     Constructs a QAxServerBase object wrapping \a o.
 */
 QAxServerBase::QAxServerBase(QObject *o)
@@ -1082,7 +1082,7 @@ QAxServerBase::QAxServerBase(QObject *o)
     internalConnect();
 }
 
-/*!
+/*! \internal
     Initializes data members.
 */
 void QAxServerBase::init()
@@ -1124,7 +1124,7 @@ void QAxServerBase::init()
     points[IID_IPropertyNotifySink] = new QAxConnection(this, IID_IPropertyNotifySink);
 }
 
-/*!
+/*! \internal
     Destroys the QAxServerBase object, releasing all allocated
     resources and interfaces.
 */
@@ -1176,7 +1176,7 @@ QAxServerBase::~QAxServerBase()
     qAxUnlock();
 }
 
-/*
+/*  \internal
     Registering with OLE
 */
 void QAxServerBase::registerActiveObject(IUnknown *object)
@@ -1198,7 +1198,7 @@ void QAxServerBase::revokeActiveObject()
     ole_ref = 0;
 }
 
-/*
+/* \internal
     QueryInterface implementation.
 */
 HRESULT WINAPI QAxServerBase::QueryInterface(REFIID iid, void **iface)
@@ -1275,7 +1275,7 @@ HRESULT QAxServerBase::InternalQueryInterface(REFIID iid, void **iface)
     return S_OK;
 }
 
-/*!
+/*! \internal
     Detects and initilaizes implementation of QAxBindable in objects.
 */
 void QAxServerBase::internalBind()
@@ -1293,7 +1293,7 @@ void QAxServerBase::internalBind()
     }
 }
 
-/*!
+/*! \internal
     Connects object signals to event dispatcher.
 */
 void QAxServerBase::internalConnect()
@@ -1312,7 +1312,7 @@ void QAxServerBase::internalConnect()
     }
 }
 
-/*!
+/*! \internal
     Creates the QWidget for the classname passed to the c'tor.
 
     All signals of the widget class are connected to the internal event mapper.
@@ -1598,7 +1598,7 @@ LRESULT QT_WIN_CALLBACK QAxServerBase::ActiveXProc(HWND hWnd, UINT uMsg, WPARAM
     return ::DefWindowProc(hWnd, uMsg, wParam, lParam);
 }
 
-/*!
+/*! \internal
     Creates the window hosting the QWidget.
 */
 HWND QAxServerBase::create(HWND hWndParent, RECT& rcPos)
@@ -1653,7 +1653,7 @@ HWND QAxServerBase::create(HWND hWndParent, RECT& rcPos)
     return hWnd;
 }
 
-/*
+/* \internal
     Recoursively creates Win32 submenus.
 */
 HMENU QAxServerBase::createPopup(QMenu *popup, HMENU oldMenu)
@@ -1696,7 +1696,7 @@ HMENU QAxServerBase::createPopup(QMenu *popup, HMENU oldMenu)
     return popupMenu;
 }
 
-/*!
+/*! \internal
     Creates a Win32 menubar.
 */
 void QAxServerBase::createMenu(QMenuBar *menuBar)
@@ -1757,7 +1757,7 @@ void QAxServerBase::createMenu(QMenuBar *menuBar)
     }
 }
 
-/*!
+/*! \internal
     Remove the Win32 menubar.
 */
 void QAxServerBase::removeMenu()
@@ -1777,7 +1777,7 @@ void QAxServerBase::removeMenu()
 extern bool ignoreSlots(const char *test);
 extern bool ignoreProps(const char *test);
 
-/*!
+/*! \internal
     Makes sure the type info is loaded
 */
 void QAxServerBase::ensureMetaData()
@@ -1837,7 +1837,7 @@ void QAxServerBase::update()
     }
 }
 
-/*!
+/*! \internal
     Resizes the control, faking a QResizeEvent if required
 */
 void QAxServerBase::resize(const QSize &size)
@@ -1927,7 +1927,7 @@ static inline QByteArray paramType(const QByteArray &ptype, bool *out)
     return ptype;
 }
 
-/*!
+/*! \internal
     Catches all signals emitted by the Qt widget and fires the respective COM event.
 
     \a isignal is the Qt Meta Object index of the received signal, and \a _o the
@@ -2121,7 +2121,7 @@ int QAxServerBase::qt_metacall(QMetaObject::Call call, int index, void **argv)
     return true;
 }
 
-/*!
+/*! \internal
     Call IPropertyNotifySink of connected clients.
     \a dispId specifies the ID of the property that changed.
 */
@@ -2169,7 +2169,7 @@ bool QAxServerBase::emitRequestPropertyChange(const char *property)
     return true;
 }
 
-/*!
+/*! \internal
     Call IPropertyNotifySink of connected clients.
     \a dispId specifies the ID of the property that changed.
 */
diff --git a/src/activeqt/doc/ActiveQtDoc b/src/activeqt/doc/ActiveQtDoc
new file mode 100644
index 0000000..4a2b06b
--- /dev/null
+++ b/src/activeqt/doc/ActiveQtDoc
@@ -0,0 +1,15 @@
+#include <QtCore/QtCore>
+#include <QtGui/QtGui>
+#include <QtWidgets/QtWidgets>
+
+#include "qaxaggregated.h"
+#include "qaxbase.h"
+#include "qaxbindable.h"
+#include "qaxfactory.h"
+#include "qaxobject.h"
+#include "qaxscript.h"
+#include "qaxselect.h"
+#include "qaxtypefunctions.h"
+#include "qaxtypes.h"
+#include "qaxwidget.h"
+#include "qaxutils_p.h"
diff --git a/src/activeqt/doc/activeqt.qdocconf b/src/activeqt/doc/activeqt.qdocconf
index 09a48a3..d92afeb 100644
--- a/src/activeqt/doc/activeqt.qdocconf
+++ b/src/activeqt/doc/activeqt.qdocconf
@@ -6,6 +6,14 @@ version                 = $QT_VERSION
 
 qhp.projects            = ActiveQt
 
+moduleheader            = ActiveQtDoc
+
+includepaths            = -I . \
+                          -I ../container \
+                          -I ../control \
+                          -I ../shared \
+                          -I $QT_INSTALL_HEADERS
+
 qhp.ActiveQt.file         = activeqt.qhp
 qhp.ActiveQt.namespace           = org.qt-project.activeqt.$QT_VERSION_TAG
 qhp.ActiveQt.virtualFolder       = activeqt
@@ -33,11 +41,9 @@ depends                 += qtcore qtdesigner qtdoc qtopengl qtscript qtwidgets q
 
 headerdirs  += ..
 
-sourcedirs  += .. \
-               src/examples
+sourcedirs  += ..
 
 exampledirs += ../../../examples/ \
-               src/examples/ \
                snippets
 
 imagedirs   += images
diff --git a/src/activeqt/shared/qaxtypes.cpp b/src/activeqt/shared/qaxtypes.cpp
index ffbe52c..6146c83 100644
--- a/src/activeqt/shared/qaxtypes.cpp
+++ b/src/activeqt/shared/qaxtypes.cpp
@@ -743,7 +743,7 @@ bool QVariantToVARIANT(const QVariant &var, VARIANT &arg, const QByteArray &type
 
 #undef QVARIANT_TO_VARIANT_POD
 
-/*!
+/*
     Returns \a arg as a QVariant of type \a type.
 
     Used by