Doc: Fix documentation warnings for Qt 3D Core

This change fixes multiple QDoc warnings for Qt 3D Core that are
related to how Clang parses the source code and the \fn QDoc
commands.

We still have a number of 'No documentation for ...' warnings left -
those are not addressed in this change.

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

16 files changed, 47 insertions, 53 deletions

diff --git a/src/core/aspects/qabstractaspect.cpp b/src/core/aspects/qabstractaspect.cpp
index 2e37df60b..e793eebca 100644
--- a/src/core/aspects/qabstractaspect.cpp
+++ b/src/core/aspects/qabstractaspect.cpp
@@ -96,17 +96,11 @@ void QAbstractAspectPrivate::unregisterBackendType(const QMetaObject &mo)
  */
 
 /*!
- * \fn void QAbstractAspect::registerBackendType(const QBackendNodeMapperPtr &functor)
+ * \fn void Qt3DCore::QAbstractAspect::registerBackendType(const Qt3DCore::QBackendNodeMapperPtr &functor)
  * Registers backend with \a functor.
  */
 
 /*!
- * \internal
- * \fn void registerBackendType(const QBackendNodeMapperPtr &functor)
- * This is a workaround to fix an erroneous qdoc warning. KEEP IT INTERNAL
- */
-
-/*!
  * Constructs a new QAbstractAspect with \a parent
  */
 QAbstractAspect::QAbstractAspect(QObject *parent)
diff --git a/src/core/aspects/qaspectengine.cpp b/src/core/aspects/qaspectengine.cpp
index 1467f0cff..b7a8c84b1 100644
--- a/src/core/aspects/qaspectengine.cpp
+++ b/src/core/aspects/qaspectengine.cpp
@@ -276,8 +276,8 @@ void QAspectEnginePrivate::exitSimulationLoop()
 /*!
  * Registers a new \a aspect to the AspectManager. The QAspectEngine takes
  * ownership of the aspect and will delete it when the aspect is unregistered.
+ //! Called in the main thread
  */
-// Called in the main thread
 void QAspectEngine::registerAspect(QAbstractAspect *aspect)
 {
     Q_D(QAspectEngine);
diff --git a/src/core/aspects/qaspectmanager.cpp b/src/core/aspects/qaspectmanager.cpp
index e2f0d9383..375a4ed83 100644
--- a/src/core/aspects/qaspectmanager.cpp
+++ b/src/core/aspects/qaspectmanager.cpp
@@ -198,6 +198,8 @@ void QAspectManager::setRootEntity(Qt3DCore::QEntity *root, const QVector<Qt3DCo
 }
 
 /*!
+ * \fn void Qt3DCore::QAspectManager::registerAspect(Qt3DCore::QAbstractAspect *aspect)
+ *
  * Registers a new \a aspect.
  */
 void QAspectManager::registerAspect(QAbstractAspect *aspect)
diff --git a/src/core/changes/qskeletoncreatedchange.cpp b/src/core/changes/qskeletoncreatedchange.cpp
index c1d58150d..80895c394 100644
--- a/src/core/changes/qskeletoncreatedchange.cpp
+++ b/src/core/changes/qskeletoncreatedchange.cpp
@@ -49,10 +49,11 @@ QSkeletonCreatedChangeBasePrivate::QSkeletonCreatedChangeBasePrivate(const QAbst
 
 }
 
-/*!
-    \class QSkeletonCreatedChangeBase
+/*
+    \internal
+    \class Qt3DCore::QSkeletonCreatedChangeBase
     \inmodule Qt3DCore
-    \brief Base class for handling creation changes for QAbstractSkeleton sub-classes
+    \brief Base class for handling creation changes for QAbstractSkeleton sub-classes.
 */
 QSkeletonCreatedChangeBase::QSkeletonCreatedChangeBase(const QAbstractSkeleton *skeleton)
     : Qt3DCore::QNodeCreatedChangeBase(*new QSkeletonCreatedChangeBasePrivate(skeleton), skeleton)
diff --git a/src/core/jobs/qabstractaspectjobmanager.cpp b/src/core/jobs/qabstractaspectjobmanager.cpp
index 97cce61d8..5d921c778 100644
--- a/src/core/jobs/qabstractaspectjobmanager.cpp
+++ b/src/core/jobs/qabstractaspectjobmanager.cpp
@@ -43,10 +43,11 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DCore {
 
-/*!
-    \class QAbstractAspectJobManager
+/*
+    \internal
+    \class Qt3DCore::QAbstractAspectJobManager
     \inmodule Qt3DCore
-    \brief A job manager for QAbstractAspect subclasses
+    \brief A job manager for QAbstractAspect subclasses.
 */
 QAbstractAspectJobManager::QAbstractAspectJobManager(QObject *parent)
     : QObject(parent)
diff --git a/src/core/jobs/qaspectjob.cpp b/src/core/jobs/qaspectjob.cpp
index 6016bd273..7b880cb93 100644
--- a/src/core/jobs/qaspectjob.cpp
+++ b/src/core/jobs/qaspectjob.cpp
@@ -77,8 +77,8 @@ QAspectJob::QAspectJob()
  */
 
 /*!
- * \fn void QAspectJob::run()
- * Executes job.
+ * \fn void Qt3DCore::QAspectJob::run()
+ * Executes the job.
  */
 
 /*!
diff --git a/src/core/nodes/propertychangehandler.cpp b/src/core/nodes/propertychangehandler.cpp
index 218d76f10..0a1d59932 100644
--- a/src/core/nodes/propertychangehandler.cpp
+++ b/src/core/nodes/propertychangehandler.cpp
@@ -43,10 +43,11 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DCore {
 
-/*!
-    \class PropertyChangeHandlerBase
+/*
+    \internal
+    \class Qt3DCore::PropertyChangeHandlerBase
     \inmodule Qt3DCore
-    \brief Base class for the property change handler
+    \brief Base class for the property change handler.
 */
 PropertyChangeHandlerBase::PropertyChangeHandlerBase(QObject *parent) :
     QObject(parent)
diff --git a/src/core/nodes/qabstractnodefactory.cpp b/src/core/nodes/qabstractnodefactory.cpp
index 41d82cf38..dbdfc641b 100644
--- a/src/core/nodes/qabstractnodefactory.cpp
+++ b/src/core/nodes/qabstractnodefactory.cpp
@@ -43,26 +43,26 @@ QT_BEGIN_NAMESPACE
 
 namespace Qt3DCore {
 
-/*!
+/*
+ * \internal
  * \class Qt3DCore::QAbstractNodeFactory
  * \inheaderfile Qt3DCore/QAbstractNodeFactory
  * \inmodule Qt3DCore
  *
- * TODO
+ * \TODO
  */
 
-/*!
- * \fn QNode *QAbstractNodeFactory::createNode(const char *type)
+/*
+ * \fn Qt3DCore::QNode * Qt3DCore::QAbstractNodeFactory::createNode(const char *type)
  * Creates a node of \a type.
  */
-
 QAbstractNodeFactory::~QAbstractNodeFactory()
 {
 }
 
 QVector<QAbstractNodeFactory *> node_factories;
 
-/*!
+/*
  * Registers the given \a factory
  */
 void QAbstractNodeFactory::registerNodeFactory(QAbstractNodeFactory *factory)
@@ -70,7 +70,7 @@ void QAbstractNodeFactory::registerNodeFactory(QAbstractNodeFactory *factory)
     node_factories << factory;
 }
 
-/*!
+/*
  * \return the node factories.
  */
 QVector<QAbstractNodeFactory *> QAbstractNodeFactory::nodeFactories()
diff --git a/src/core/nodes/qbackendnode.cpp b/src/core/nodes/qbackendnode.cpp
index 65d140067..00e957165 100644
--- a/src/core/nodes/qbackendnode.cpp
+++ b/src/core/nodes/qbackendnode.cpp
@@ -104,9 +104,9 @@ QBackendNodePrivate *QBackendNodePrivate::get(QBackendNode *n)
  */
 
 /*!
- * \fn QBackendNode *QBackendNodeMapper::create(const QNodeCreatedChangeBasePtr &change) const
+ * \fn Qt3DCore::QBackendNode *Qt3DCore::QBackendNodeMapper::create(const Qt3DCore::QNodeCreatedChangeBasePtr &change) const
  *
- * TODO
+ * \TODO
  *
  * \a change
  *
@@ -114,13 +114,13 @@ QBackendNodePrivate *QBackendNodePrivate::get(QBackendNode *n)
  */
 
 /*!
- * \fn QBackendNode *QBackendNodeMapper::get(QNodeId id) const
+ * \fn Qt3DCore::QBackendNode * Qt3DCore::QBackendNodeMapper::get(Qt3DCore::QNodeId id) const
  *
  * \return backend node for the given node \a id.
  */
 
 /*!
- * \fn void QBackendNodeMapper::destroy(QNodeId id) const
+ * \fn void Qt3DCore::QBackendNodeMapper::destroy(Qt3DCore::QNodeId id) const
  *
  * Destroys the backend node for the given node \a id.
  */
diff --git a/src/core/nodes/qentity.cpp b/src/core/nodes/qentity.cpp
index 9bc41f8cc..d0ed58efd 100644
--- a/src/core/nodes/qentity.cpp
+++ b/src/core/nodes/qentity.cpp
@@ -210,7 +210,9 @@ QEntity *QEntity::parentEntity() const
     return parentEntity;
 }
 
-/*!
+/*
+    \internal
+
     Returns the Qt3DCore::QNodeId id of the parent Qt3DCore::QEntity instance of the
     current Qt3DCore::QEntity object. The QNodeId isNull method will return true if
     there is no Qt3DCore::QEntity parent of the current Qt3DCore::QEntity in the scene
diff --git a/src/core/nodes/qnode.cpp b/src/core/nodes/qnode.cpp
index 083fda7df..316608c63 100644
--- a/src/core/nodes/qnode.cpp
+++ b/src/core/nodes/qnode.cpp
@@ -700,13 +700,13 @@ void QNodePrivate::nodePtrDeleter(QNode *q)
 }
 
 /*!
-    \fn QNodeId qIdForNode(QNode *node)
+    \fn Qt3DCore::QNodeId Qt3DCore::qIdForNode(Qt3DCore::QNode *node)
     \relates Qt3DCore::QNode
     \return node id for \a node.
 */
 
 /*!
-    \fn QNodeIdVector qIdsForNodes(const T &nodes)
+    \fn template<typename T> Qt3DCore::QNodeIdVector Qt3DCore::qIdsForNodes(const T &nodes)
     \relates Qt3DCore::QNode
     \return vector of node ids for \a nodes.
 */
@@ -732,8 +732,8 @@ QNode::QNode(QNodePrivate &dd, QNode *parent)
 }
 
 /*!
-    \fn QNode::nodeDestroyed()
-    emitted when the node is destroyed.
+    \fn Qt3DCore::QNode::nodeDestroyed()
+    Emitted when the node is destroyed.
 */
 
 /*! \internal */
diff --git a/src/core/nodes/qnodeid.cpp b/src/core/nodes/qnodeid.cpp
index 17bc4e8e1..7e392137e 100644
--- a/src/core/nodes/qnodeid.cpp
+++ b/src/core/nodes/qnodeid.cpp
@@ -54,12 +54,12 @@ namespace Qt3DCore {
  * \typedef Qt3DCore::QNodeIdVector
  * \relates Qt3DCore::QNodeId
  *
- * A vector of {QNodeId}s.
+ * A vector of \l {QNodeId}s.
  */
 
 /*!
- * \fn bool QNodeId::isNull() const
- * \return TODO
+ * \fn bool Qt3DCore::QNodeId::isNull() const
+ * \return \TODO
  */
 
 /*!
@@ -83,13 +83,13 @@ namespace Qt3DCore {
  */
 
 /*!
- * \fn quint64 QNodeId::id() const
- * \return TODO
+ * \fn quint64 Qt3DCore::QNodeId::id() const
+ * \return \TODO
  */
 
 /*!
  * \fn Qt3DCore::QNodeId::operator bool() const
- * TODO
+ * \TODO
  */
 
 /*!
diff --git a/src/core/qpostman.cpp b/src/core/qpostman.cpp
index 9fd8f9104..6d6484f18 100644
--- a/src/core/qpostman.cpp
+++ b/src/core/qpostman.cpp
@@ -94,7 +94,8 @@ static inline QMetaMethod submitChangeBatchMethod()
     return QPostman::staticMetaObject.method(idx);
 }
 
-/*!
+/*
+ * \internal
  * This will start or append \a change to a batch of changes from frontend
  * nodes. Once the batch is complete, when the event loop returns, the batch is
  * sent to the QChangeArbiter to notify the backend aspects.
diff --git a/src/core/transforms/qjoint.cpp b/src/core/transforms/qjoint.cpp
index 3f631ec98..a4f259ce9 100644
--- a/src/core/transforms/qjoint.cpp
+++ b/src/core/transforms/qjoint.cpp
@@ -109,7 +109,7 @@ QJointPrivate::QJointPrivate()
 */
 
 /*!
-    \qmlproperty matrix4x4 inverseBindMatrix
+    \qmlproperty matrix4x4 Joint::inverseBindMatrix
 
     Holds the inverse bind matrix of the joint. This is used to transform
     vertices from model space into the space of this joint so they can
diff --git a/src/quick3d/quick3d/items/quick3dnodev9.cpp b/src/quick3d/quick3d/items/quick3dnodev9.cpp
index d1a9011b5..40edadbc4 100644
--- a/src/quick3d/quick3d/items/quick3dnodev9.cpp
+++ b/src/quick3d/quick3d/items/quick3dnodev9.cpp
@@ -90,11 +90,6 @@ void Quick3DNodeV9::setPropertyTrackingOverrides(const QJSValue &value)
     emit propertyTrackingOverridesChanged(value);
 }
 
-/*!
-    \qmlproperty list<QtQml::QtObject> Qt3DCore::Node::data
-    \default
-*/
-
 QQmlListProperty<QObject> Quick3DNodeV9::data()
 {
     return QQmlListProperty<QObject>(this, 0,
@@ -104,11 +99,6 @@ QQmlListProperty<QObject> Quick3DNodeV9::data()
                                      Quick3DNodeV9::clearData);
 }
 
-/*!
-    \qmlproperty list<Node> Qt3DCore::Node::childNodes
-    \readonly
-*/
-
 QQmlListProperty<QNode> Quick3DNodeV9::childNodes()
 {
     return QQmlListProperty<QNode>(this, 0,
diff --git a/src/quick3d/quick3d/qqmlaspectengine.cpp b/src/quick3d/quick3d/qqmlaspectengine.cpp
index 912c71fb3..df555ab98 100644
--- a/src/quick3d/quick3d/qqmlaspectengine.cpp
+++ b/src/quick3d/quick3d/qqmlaspectengine.cpp
@@ -52,6 +52,8 @@ namespace Quick {
 /*!
     \namespace Qt3DCore::Quick
     \inmodule Qt3DCore
+    \ingroup qt3d-namespaces
+
     \brief Contains classes used for implementing QML functionality into Qt3D
     applications.
 */