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>

6 files changed, 28 insertions, 25 deletions

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
  */
 
 /*!