Doc: Fix documentation warnings

Pick-to: 6.0 6.0.0
Fixes: QTBUG-88842
Change-Id: Ie8ea1914c5e740c0c4bf25f4754a008aff6401cd
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

8 files changed, 57 insertions, 156 deletions

diff --git a/src/core/geometry/qboundingvolume.cpp b/src/core/geometry/qboundingvolume.cpp
index ebe524601..54bf9ffa8 100644
--- a/src/core/geometry/qboundingvolume.cpp
+++ b/src/core/geometry/qboundingvolume.cpp
@@ -154,42 +154,41 @@ QBoundingVolumePrivate *QBoundingVolumePrivate::get(QBoundingVolume *q)
  */
 
 /*!
- * \class Qt3DCore::QBoundingVolume
- * \inheaderfile Qt3DCore/QBoundingVolume
- * \inmodule Qt3DCore
- * \inherits Qt3DCore::QComponent
- * \since 6.0
- *
- * \brief can be used to override an entity's bounding volume.
- *
- * An entity's bounding volume is used for many operations such as
- * picking or view frustum culling. It is normally computed by
- * traversing the rendered geometry.
- *
- * QBoundingVolume can be used when the extent of the geometry is
- * known to the application so that Qt 3D does not have to
- * compute it.
- *
- * A bounding volume can be provided either as minimum and maximum
- * extent coordinates, or a separate, usually simpler, geometry
- * that approximates the rendered mesh.
- *
- * When using minimum and maximum extents, these are considered
- * to be the opposite corners of an axis aligned bounding box,
- * in the geometry's local coordinate system.
- *
- * QBoundingVolume can also be used to query the computed bounding
- * volume of a GeometryView. The implicitMinPoint and implicitMaxPoint
- * properties will be updated if the geometry changes. Note that this
- * is done asynchronously on a background thread so you should check
- * the value of implicitPointsValid before reading them.
- *
- * You can force the implicit extents to be updated by calling
- * updateImplicitBounds. This will block on the calling thread until
- * the results are available.
- *
- * \note GeometryRenderer inherits BoundingVolume and thus supports
- * reading implicit bounds or setting explicit bounds also.
+    \class Qt3DCore::QBoundingVolume
+    \inheaderfile Qt3DCore/QBoundingVolume
+    \inmodule Qt3DCore
+    \inherits Qt3DCore::QComponent
+    \since 6.0
+    \brief can be used to override the bounding volume of an entity.
+
+    An entity's bounding volume is used for many operations such as
+    picking or view frustum culling. It is normally computed by
+    traversing the rendered geometry.
+
+    QBoundingVolume can be used when the extent of the geometry is
+    known to the application so that Qt 3D does not have to
+    compute it.
+
+    A bounding volume can be provided either as minimum and maximum
+    extent coordinates, or a separate, usually simpler, geometry
+    that approximates the rendered mesh.
+
+    When using minimum and maximum extents, these are considered
+    to be the opposite corners of an axis aligned bounding box,
+    in the geometry's local coordinate system.
+
+    QBoundingVolume can also be used to query the computed bounding
+    volume of a GeometryView. The implicitMinPoint and implicitMaxPoint
+    properties will be updated if the geometry changes. Note that this
+    is done asynchronously on a background thread so you should check
+    the value of implicitPointsValid before reading them.
+
+    You can force the implicit extents to be updated by calling
+    updateImplicitBounds. This will block on the calling thread until
+    the results are available.
+
+    \note GeometryRenderer inherits BoundingVolume and thus supports
+    reading implicit bounds or setting explicit bounds also.
 */
 
 /*!
@@ -222,7 +221,7 @@ QBoundingVolume::~QBoundingVolume()
 * to compute the bounding volume.
 */
 /*!
-* \property QAttribute::view
+* \property QBoundingVolume::view
 *
 * Holds a pointer to the instance of QGeometryView which will be used, if set,
 * to compute the bounding volume.
@@ -239,7 +238,7 @@ QGeometryView *QBoundingVolume::view() const
 * Holds minimum extent of the bounding volume computed from the specified view.
 */
 /*!
-* \property QAttribute::implicitMinPoint
+* \property QBoundingVolume::implicitMinPoint
 *
 * Holds minimum extent of the bounding volume computed from the specified view.
 */
@@ -255,7 +254,7 @@ QVector3D QBoundingVolume::implicitMinPoint() const
 * Holds maximum extent of the bounding volume computed from the specified view.
 */
 /*!
-* \property QAttribute::implicitMaxPoint
+* \property QBoundingVolume::implicitMaxPoint
 *
 * Holds maximum extent of the bounding volume computed from the specified view.
 */
@@ -273,7 +272,7 @@ QVector3D QBoundingVolume::implicitMaxPoint() const
 * \sa updateImplicitBounds
 */
 /*!
-* \property QAttribute::implicitPointsValid
+* \property QBoundingVolume::implicitPointsValid
 *
 * True if a view has been assigned and the implicit extent properties are up to date.
 *
@@ -293,7 +292,7 @@ bool QBoundingVolume::areImplicitPointsValid() const
 * geometry.
 */
 /*!
-* \property QAttribute::minPoint
+* \property QBoundingVolume::minPoint
 *
 * User specified minimum extent of the bounding volume. When set (along with maximum
 * extent), this will be used internally to avoid computing the volume from the
@@ -313,7 +312,7 @@ QVector3D QBoundingVolume::minPoint() const
 * geometry.
 */
 /*!
-* \property QAttribute::maxPoint
+* \property QBoundingVolume::maxPoint
 *
 * User specified maximum extent of the bounding volume. When set (along with minimum
 * extent), this will be used internally to avoid computing the volume from the
@@ -354,10 +353,18 @@ void QBoundingVolume::setMaxPoint(const QVector3D &maxPoint)
 }
 
 /*!
-* \brief QBoundingVolume::updateImplicitBounds
+* \qmlmethod bool BoundingVolume::updateImplicitBounds()
 *
 * Updates the implicit bounds of the specified view. Returns
-* true if the computation succeeded and false otherwise.
+* \c true if the computation succeeded and false otherwise.
+*
+* \note The calculations are done in the call thread, this
+* could take significant time for large meshes.
+*/
+
+/*!
+* Updates the implicit bounds of the specified view. Returns
+* \c true if the computation succeeded and false otherwise.
 *
 * \note The calculations are done in the call thread, this
 * could take significant time for large meshes.
diff --git a/src/core/geometry/qbuffer.cpp b/src/core/geometry/qbuffer.cpp
index c94b59206..9169442f1 100644
--- a/src/core/geometry/qbuffer.cpp
+++ b/src/core/geometry/qbuffer.cpp
@@ -122,29 +122,6 @@ void QBufferPrivate::setData(const QByteArray &data)
  */
 
 /*!
- * \enum QBuffer::BufferType
- *
- * The type of the buffer.
- *
- * \value VertexBuffer
- *        GL_ARRAY_BUFFER
- * \value IndexBuffer
- *        GL_ELEMENT_ARRAY_BUFFER
- * \value PixelPackBuffer
- *        GL_PIXEL_PACK_BUFFER
- * \value PixelUnpackBuffer
- *        GL_PIXEL_UNPACK_BUFFER
- * \value UniformBuffer
- *        GL_UNIFORM_BUFFER
- * \value ShaderStorageBuffer
- *        GL_SHADER_STORAGE_BUFFER
- * \value DrawIndirectBuffer
- *        GL_DRAW_INDIRECT_BUFFER
- *
- * \deprecated
- */
-
-/*!
  * \enum QBuffer::UsageType
  *
  * The type of the usage.
@@ -181,11 +158,6 @@ void QBufferPrivate::setData(const QByteArray &data)
  */
 
 /*!
- * \typedef Qt3DCore::QBufferDataGeneratorPtr
- * \relates Qt3DCore::QBuffer
- */
-
-/*!
  * Constructs a new QBuffer with \a parent.
  */
 QBuffer::QBuffer(QNode *parent)
diff --git a/src/core/geometry/qgeometry.cpp b/src/core/geometry/qgeometry.cpp
index 6b1af6804..cc459a07b 100644
--- a/src/core/geometry/qgeometry.cpp
+++ b/src/core/geometry/qgeometry.cpp
@@ -162,17 +162,6 @@ QGeometry::QGeometry(QNode *parent)
     : QGeometry(*new QGeometryPrivate(), parent) {}
 
 /*!
-    \fn Qt3DCore::QGeometryFactory::operator()()
-
-     Returns the generated geometry.
-*/
-/*!
-    \fn bool Qt3DCore::QGeometryFactory::operator==(const QGeometryFactory &other) const = 0
-
-    Compares the factory with the factory specified in \a other.
-    Returns true if they are equal.
-*/
-/*!
     \internal
  */
 QGeometry::~QGeometry()
diff --git a/src/core/jobs/qaspectjob.cpp b/src/core/jobs/qaspectjob.cpp
index 186624aec..cf4fb07d6 100644
--- a/src/core/jobs/qaspectjob.cpp
+++ b/src/core/jobs/qaspectjob.cpp
@@ -153,8 +153,9 @@ const std::vector<QWeakPointer<QAspectJob> > &QAspectJob::dependencies() const
 }
 
 /*!
- * This is called, in the main thread, when all the jobs have completed.
- * It's a good point to push changes back to the frontend.
+ * Called in the main thread when all the jobs have completed.
+ * This is a good point to push changes back to the frontend.
+ * \a aspectEngine is the engine responsible for the run loop.
  */
 void QAspectJob::postFrame(QAspectEngine *aspectEngine)
 {
diff --git a/src/core/nodes/qbackendnode.cpp b/src/core/nodes/qbackendnode.cpp
index ae7a3023b..9855baeb2 100644
--- a/src/core/nodes/qbackendnode.cpp
+++ b/src/core/nodes/qbackendnode.cpp
@@ -106,7 +106,7 @@ void QBackendNodePrivate::componentRemoved(QNode *frontend)
  *
  * \TODO
  *
- * \a change
+ * \a id
  *
  * \return created node.
  */
diff --git a/src/core/nodes/qnode.cpp b/src/core/nodes/qnode.cpp
index baf9525cb..d9ab8f0dc 100644
--- a/src/core/nodes/qnode.cpp
+++ b/src/core/nodes/qnode.cpp
@@ -631,36 +631,6 @@ void QNodePrivate::nodePtrDeleter(QNode *q)
 */
 
 /*!
-    \fn void Qt3DCore::QNodeCommand::setReplyToCommandId(CommandId id)
-
-    Sets the command \a id to which the message is a reply.
-
-*/
-/*!
-    \fn  Qt3DCore::QNode::PropertyTrackingMode Qt3DCore::QNode::defaultPropertyTrackingMode() const
-
-    Returns the default property tracking mode which determines whether a
-    QNode should be listening for property updates.
-
-*/
-/*!
-    \fn Qt3DCore::QNode::clearPropertyTracking(const QString &propertyName)
-
-    Clears the tracking property called \a propertyName.
-*/
-/*!
-    \fn Qt3DCore::QNode::PropertyTrackingMode Qt3DCore::QNode::propertyTracking(const QString &propertyName) const
-
-    Returns the tracking mode of \a propertyName.
-*/
-
-/*!
-    \fn Qt3DCore::QNode::setPropertyTracking(const QString &propertyName, Qt3DCore::QNode::PropertyTrackingMode trackMode)
-
-    Sets the property tracking for \a propertyName and \a trackMode.
-*/
-
-/*!
      Creates a new QNode instance with parent \a parent.
 
      \note The backend aspects will be notified that a QNode instance is
@@ -839,45 +809,6 @@ bool QNode::isEnabled() const
     return d->m_enabled;
 }
 
-/*!
-   \fn Qt3DCore::QNodeCommand::CommandId Qt3DCore::QNodeCommand::inReplyTo() const
-
-   Returns the id of the original QNodeCommand message that
-   was sent to the backend.
-
-*/
-/*!
-    \fn void Qt3DCore::QNodeCommand::setData(const QVariant &data)
-
-    Sets the data (\a data) in the backend node to perform
-    the operations requested.
-*/
-/*!
-    \fn void Qt3DCore::QNodeCommand::setName(const QString &name)
-
-
-    Sets the data (\a name) in the backend node to perform
-    the operations requested.
-*/
-
-/*!
-    \enum Qt3DCore::QNode::PropertyTrackingMode
-
-    Indicates how a QNode listens for property updates.
-
-    \value TrackFinalValues
-           Tracks final values
-    \value DontTrackValues
-           Does not track values
-    \value TrackAllValues
-           Tracks all values
-*/
-/*!
-    \fn Qt3DCore::QNode::clearPropertyTrackings()
-
-    Erases all values that have been saved by the property tracking.
-*/
-
 namespace {
 
 /*! \internal */
diff --git a/src/core/nodes/qnodeid.cpp b/src/core/nodes/qnodeid.cpp
index 2e4d10374..459c41654 100644
--- a/src/core/nodes/qnodeid.cpp
+++ b/src/core/nodes/qnodeid.cpp
@@ -93,7 +93,7 @@ namespace Qt3DCore {
  */
 
 /*!
- * \fn uint Qt3DCore::qHash(QNodeId id, uint seed = 0)
+ * \fn [nodeid-qhash] constexpr size_t Qt3DCore::qHash(QNodeId id, uint seed)
  * \relates Qt3DCore::QNodeId
  * \return hash of node with \a id and optional \a seed.
  */
diff --git a/src/core/nodes/qnodeid.h b/src/core/nodes/qnodeid.h
index a51ce684f..487cbcab1 100644
--- a/src/core/nodes/qnodeid.h
+++ b/src/core/nodes/qnodeid.h
@@ -106,6 +106,7 @@ using QNodeIdVector = QList<QNodeId>;
 Q_3DCORESHARED_EXPORT QDebug operator<<(QDebug d, QNodeId id);
 #endif
 
+//! [nodeid-qhash]
 inline constexpr size_t qHash(QNodeId id, size_t seed = 0) noexcept
 {
     using QT_PREPEND_NAMESPACE(qHash);