Fix documentation of QRenderSettings and QPickingSettings

Task-number: QTBUG-55697
Change-Id: I7a357f6f00b62c1ef2042f4088374dcd34005110
Reviewed-by: Antti Määttä <antti.maatta@qt.io>
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

2 files changed, 133 insertions, 52 deletions

diff --git a/src/render/frontend/qpickingsettings.cpp b/src/render/frontend/qpickingsettings.cpp
index 0e152f5f1..e1c403ba3 100644
--- a/src/render/frontend/qpickingsettings.cpp
+++ b/src/render/frontend/qpickingsettings.cpp
@@ -45,12 +45,25 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
- * \class Qt3DRender::QPickingSettings
- * \brief The QPickingSettings class specifies the current framegraph to be used
- * by the renderer and specifies whether rendering is always active or updated
- * only on changes.
- * \since 5.7
- * \inmodule Qt3DRender
+    \class Qt3DRender::QPickingSettings
+    \brief The QPickingSettings class specifies how entity picking is handled.
+    \since 5.7
+    \inmodule Qt3DRender
+    \inherits Qt3DCore::QNode
+
+    The picking settings determine how the entity picking is handled. For more details about
+    entity picking, see QObjectPicker component documentation.
+ */
+
+/*!
+    \qmltype PickingSettings
+    \brief The PickingSettings class specifies how entity picking is handled.
+    \since 5.7
+    \inqmlmodule Qt3D.Render
+    \instantiates Qt3DRender::QPickingSettings
+
+    The picking settings determine how the entity picking is handled. For more details about
+    entity picking, see Qt3DRender::QObjectPicker component documentation.
  */
 
 QPickingSettingsPrivate::QPickingSettingsPrivate()
@@ -60,11 +73,6 @@ QPickingSettingsPrivate::QPickingSettingsPrivate()
 {
 }
 
-/*!
- * The constructor creates a new Qt3DRender::QPickingSettings
- * instance with the specified \a parent.
- * \param parent
- */
 QPickingSettings::QPickingSettings(Qt3DCore::QNode *parent)
     : Qt3DCore::QNode(*new QPickingSettingsPrivate, parent)
 {
@@ -81,18 +89,12 @@ QPickingSettings::QPickingSettings(QPickingSettingsPrivate &dd, Qt3DCore::QNode
 {
 }
 
-/*!
- * \return the current pick method.
- */
 QPickingSettings::PickMethod QPickingSettings::pickMethod() const
 {
     Q_D(const QPickingSettings);
     return d->m_pickMethod;
 }
 
-/*!
- * \return the current pick result mode.
- */
 QPickingSettings::PickResultMode QPickingSettings::pickResultMode() const
 {
     Q_D(const QPickingSettings);
@@ -102,16 +104,31 @@ QPickingSettings::PickResultMode QPickingSettings::pickResultMode() const
 /*!
  * \enum Qt3DRender::QPickingSettings::PickMethod
  *
- * Specifies which parameters of Qt3DRender::QPickingSettings are used.
+ * Specifies the picking method.
  *
- * \value BoundingVolumePicking
- * \value TrianglePicking
+ * \value BoundingVolumePicking An entity is considered picked if the picking ray intersects
+ * the bounding volume of the entity.
+ * \value TrianglePicking An entity is considered picked if the picking ray intersects with
+ * any triangle of the entity's mesh component.
  */
 
 /*!
- * Sets the pick method to \a pickMethod
- * \param pickMethod
- */
+    \qmlproperty enumeration PickingSettings::pickMethod
+
+    Holds the current pick method.
+
+    \list
+        \li PickingSettings.BoundingVolumePicking
+        \li PickingSettings.TrianglePicking
+    \endlist
+
+    \sa Qt3DRender::QPickingSettings::PickMethod
+*/
+/*!
+    \property QPickingSettings::pickMethod
+
+    Holds the current pick method.
+*/
 void QPickingSettings::setPickMethod(QPickingSettings::PickMethod pickMethod)
 {
     Q_D(QPickingSettings);
@@ -125,16 +142,30 @@ void QPickingSettings::setPickMethod(QPickingSettings::PickMethod pickMethod)
 /*!
  * \enum Qt3DRender::QPickingSettings::PickResultMode
  *
- * Specifies which parameters of Qt3DRender::PickResultMode are used.
+ * Specifies what is included into the picking results.
  *
- * \value NearestPick
- * \value AllPicks
+ * \value NearestPick Only the nearest entity to picking ray origin intersected by the picking ray
+ * is picked.
+ * \value AllPicks All entities that intersect the picking ray are picked.
  */
 
 /*!
- * Sets the pick result mode to \a pickResultMode
- * \param pickResultMode
- */
+    \qmlproperty enumeration PickingSettings::pickResultMode
+
+    Holds the current pick results mode.
+
+    \list
+        \li PickingSettings.NearestPick
+        \li PickingSettings.AllPicks
+    \endlist
+
+    \sa Qt3DRender::QPickingSettings::PickResultMode
+*/
+/*!
+    \property QPickingSettings::pickResultMode
+
+    Holds the current pick results mode.
+*/
 void QPickingSettings::setPickResultMode(QPickingSettings::PickResultMode pickResultMode)
 {
     Q_D(QPickingSettings);
diff --git a/src/render/frontend/qrendersettings.cpp b/src/render/frontend/qrendersettings.cpp
index 715c9cc5e..d9ce3c3c9 100644
--- a/src/render/frontend/qrendersettings.cpp
+++ b/src/render/frontend/qrendersettings.cpp
@@ -46,10 +46,29 @@ QT_BEGIN_NAMESPACE
 namespace Qt3DRender {
 
 /*!
- * \class Qt3DRender::QRenderSettings
- * \brief The QRenderSettings class
- * \since 5.7
- * \inmodule Qt3DRender
+   \class Qt3DRender::QRenderSettings
+   \brief The QRenderSettings class holds settings related to rendering process and host the active
+   \l{Qt 3D Render Framegraph}{FrameGraph}.
+   \since 5.7
+   \inmodule Qt3DRender
+   \inherits Qt3DCore::QComponent
+
+   The QRenderSettings component must be set as a component of the scene root entity. It specifies
+   render policy and picking settings, as well as hosts the active
+   \l{Qt 3D Render Framegraph}{FrameGraph}.
+ */
+
+/*!
+   \qmltype RenderSettings
+   \brief The RenderSettings type holds settings related to rendering process and host the active
+   \l{Qt 3D Render Framegraph}{FrameGraph}.
+   \since 5.7
+   \inqmlmodule Qt3D.Render
+   \instantiates Qt3DRender::QRenderSettings
+
+   The RenderSettings component must be set as a component of the scene root entity. It specifies
+   render policy and picking settings, as well as hosts the active
+   \l{Qt 3D Render Framegraph}{FrameGraph}.
  */
 
 /*! \internal */
@@ -82,11 +101,6 @@ void QRenderSettingsPrivate::_q_onPickResultModeChanged(QPickingSettings::PickRe
     notifyPropertyChange("pickResultMode", pickResultMode);
 }
 
-/*!
- * The constructor creates a new QRenderSettings::QRenderSettings instance with the
- * specified \a parent.
- * \param parent
- */
 QRenderSettings::QRenderSettings(Qt3DCore::QNode *parent)
     : QRenderSettings(*new QRenderSettingsPrivate, parent) {}
 
@@ -104,8 +118,19 @@ QRenderSettings::~QRenderSettings()
 }
 
 /*!
- * \return the current picking settings.
- */
+    \qmlproperty PickingSettings RenderSettings::pickingSettings
+
+    Holds the current pick settings for the \l{Qt 3D Render Framegraph}{FrameGraph}.
+
+    \readonly
+*/
+/*!
+    \property QRenderSettings::pickingSettings
+
+    Holds the current pick settings for the \l{Qt 3D Render Framegraph}{FrameGraph}.
+
+    \readonly
+*/
 QPickingSettings *QRenderSettings::pickingSettings()
 {
     Q_D(QRenderSettings);
@@ -113,27 +138,56 @@ QPickingSettings *QRenderSettings::pickingSettings()
 }
 
 /*!
- * \return the current active framegraph.
- */
+    \qmlproperty FrameGraphNode RenderSettings::activeFrameGraph
+
+    Holds the currently active \l{Qt 3D Render Framegraph}{FrameGraph}.
+*/
+/*!
+    \property QRenderSettings::activeFrameGraph
+
+    Holds the currently active \l{Qt 3D Render Framegraph}{FrameGraph}.
+*/
 QFrameGraphNode *QRenderSettings::activeFrameGraph() const
 {
     Q_D(const QRenderSettings);
     return d->m_activeFrameGraph;
 }
 
+
 /*!
- * \return the current render policy
- */
+    \enum QRenderSettings::RenderPolicy
+
+    The render policy.
+
+    \value OnDemand The \l{Qt 3D Render Framegraph}{FrameGraph} is rendered only when something
+    changes.
+    \value Always The \l{Qt 3D Render Framegraph}{FrameGraph} is rendered continuously, even if
+    nothing has changed.
+*/
+
+/*!
+    \qmlproperty enumeration RenderSettings::renderPolicy
+
+    Holds the current render policy.
+
+    \list
+        \li RenderSettings.OnDemand
+        \li RenderSettings.Always
+    \endlist
+
+    \sa Qt3DRender::QRenderSettings::RenderPolicy
+*/
+/*!
+    \property QRenderSettings::renderPolicy
+
+    Holds the current render policy.
+*/
 QRenderSettings::RenderPolicy QRenderSettings::renderPolicy() const
 {
     Q_D(const QRenderSettings);
     return d->m_renderPolicy;
 }
 
-/*!
- * Sets the active framegraph to \a activeFrameGraph.
- * \param activeFrameGraph
- */
 void QRenderSettings::setActiveFrameGraph(QFrameGraphNode *activeFrameGraph)
 {
     Q_D(QRenderSettings);
@@ -155,10 +209,6 @@ void QRenderSettings::setActiveFrameGraph(QFrameGraphNode *activeFrameGraph)
     emit activeFrameGraphChanged(activeFrameGraph);
 }
 
-/*!
- * Sets the render policy to \a renderPolicy.
- * \param renderPolicy
- */
 void QRenderSettings::setRenderPolicy(QRenderSettings::RenderPolicy renderPolicy)
 {
     Q_D(QRenderSettings);