Update documentation

And clean up old code

Change-Id: I5ff1be15d0f17450f68c1510e7b42eab3e15ea2d
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

1 files changed, 146 insertions, 5 deletions

diff --git a/src/core/geometry/qboundingvolume.cpp b/src/core/geometry/qboundingvolume.cpp
index 8f63e3d13..fd59f3fa9 100644
--- a/src/core/geometry/qboundingvolume.cpp
+++ b/src/core/geometry/qboundingvolume.cpp
@@ -118,19 +118,78 @@ QBoundingVolumePrivate *QBoundingVolumePrivate::get(QBoundingVolume *q)
  * \qmltype BoundingVolume
  * \instantiates Qt3DCore::QBoundingVolume
  * \inqmlmodule Qt3D.Core
+ * \since 2.16
  *
- * \brief
+ * \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.
+ *
+ * BoundingVolume 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.
+ *
+ * BoundingVolume 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
  *
- * \inherits Qt3DCore::QNode
+ * \brief can be used to override an entity's bounding volume
  *
- * \brief
- */
+ * 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.
+*/
 
 /*!
  * Constructs a new QBoundingVolume with \a parent.
@@ -155,37 +214,110 @@ QBoundingVolume::~QBoundingVolume()
 {
 }
 
-
+/*!
+* \qmlproperty GeometryView BoundingVolume::view
+*
+* Holds a pointer to the instance of QGeometryView which will be used, if set,
+* to compute the bounding volume.
+*/
+/*!
+* \property QAttribute::view
+*
+* Holds a pointer to the instance of QGeometryView which will be used, if set,
+* to compute the bounding volume.
+*/
 QGeometryView *QBoundingVolume::view() const
 {
     Q_D(const QBoundingVolume);
     return d->m_view;
 }
 
+/*!
+* \qmlproperty vector3d BoundingVolume::implicitMinPoint
+*
+* Holds minimum extent of the bounding volume computed from the specified view.
+*/
+/*!
+* \property QAttribute::implicitMinPoint
+*
+* Holds minimum extent of the bounding volume computed from the specified view.
+*/
 QVector3D QBoundingVolume::implicitMinPoint() const
 {
     Q_D(const QBoundingVolume);
     return d->m_implicitMinPoint;
 }
 
+/*!
+* \qmlproperty vector3d BoundingVolume::implicitMaxPoint
+*
+* Holds maximum extent of the bounding volume computed from the specified view.
+*/
+/*!
+* \property QAttribute::implicitMaxPoint
+*
+* Holds maximum extent of the bounding volume computed from the specified view.
+*/
 QVector3D QBoundingVolume::implicitMaxPoint() const
 {
     Q_D(const QBoundingVolume);
     return d->m_implicitMaxPoint;
 }
 
+/*!
+* \qmlproperty bool BoundingVolume::implicitPointsValid
+*
+* True if a view has been assigned and the implicit extent properties are up to date.
+*
+* \sa updateImplicitBounds
+*/
+/*!
+* \property QAttribute::implicitPointsValid
+*
+* True if a view has been assigned and the implicit extent properties are up to date.
+*
+* \sa updateImplicitBounds
+*/
 bool QBoundingVolume::areImplicitPointsValid() const
 {
     Q_D(const QBoundingVolume);
     return d->m_implicitPointsValid;
 }
 
+/*!
+* \qmlproperty vector3d BoundingVolume::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
+* geometry.
+*/
+/*!
+* \property QAttribute::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
+* geometry.
+*/
 QVector3D QBoundingVolume::minPoint() const
 {
     Q_D(const QBoundingVolume);
     return d->m_minPoint;
 }
 
+/*!
+* \qmlproperty vector3d BoundingVolume::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
+* geometry.
+*/
+/*!
+* \property QAttribute::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
+* geometry.
+*/
 QVector3D QBoundingVolume::maxPoint() const
 {
     Q_D(const QBoundingVolume);
@@ -220,6 +352,15 @@ void QBoundingVolume::setMaxPoint(const QVector3D &maxPoint)
     }
 }
 
+/*!
+* \brief QBoundingVolume::updateImplicitBounds
+*
+* Updates the implicit bounds of the specified view. Returns
+* 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.
+*/
 bool QBoundingVolume::updateImplicitBounds()
 {
     Q_D(QBoundingVolume);