Start of Skeletal Doc for render-materialsystem

Task-number: QTBUG-46037
Change-Id: I8f2a2ed2068cbe7a4a9265a56c99845a0322df2c
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

5 files changed, 159 insertions, 19 deletions

diff --git a/src/render/materialsystem/qeffect.cpp b/src/render/materialsystem/qeffect.cpp
index 4d02b6d79..70810676c 100644
--- a/src/render/materialsystem/qeffect.cpp
+++ b/src/render/materialsystem/qeffect.cpp
@@ -57,6 +57,27 @@ QEffectPrivate::QEffectPrivate()
 {
 }
 
+/*!
+  \class Qt3DRender::QEffect
+  \inmodule Qt3DRender
+  \since 5.7
+  \brief The base class for effects in a Qt 3D scene.
+
+ */
+
+/*!
+    \qmltype Effect
+    \instantiates Qt3DRender::QEffect
+    \inherits Node
+    \inqmlmodule Qt3D.Render
+    \since 5.7
+    \brief The base class for effects in a Qt 3D scene.
+*/
+
+/*!
+  \fn Qt3DRender::QEffect::QEffect(Qt3DCore::QNode *parent)
+  Constructs a new QEffect with the specified \a parent.
+ */
 QEffect::QEffect(QNode *parent)
     : QNode(*new QEffectPrivate, parent)
 {
@@ -73,6 +94,10 @@ QEffect::QEffect(QEffectPrivate &dd, QNode *parent)
 {
 }
 
+/*!
+ * Adds \a parameter to the effect. It sends a QPropertyNodeAddedChange to the backend.
+ * The \a parameter will be used to set a corresponding uniform value in the shader used by this effect.
+ */
 void QEffect::addParameter(QParameter *parameter)
 {
     Q_D(QEffect);
@@ -97,6 +122,9 @@ void QEffect::addParameter(QParameter *parameter)
     }
 }
 
+/*!
+ * Removes a parameter \a parameter from the effect.
+ */
 void QEffect::removeParameter(QParameter *parameter)
 {
     Q_D(QEffect);
@@ -111,6 +139,9 @@ void QEffect::removeParameter(QParameter *parameter)
     d->unregisterDestructionHelper(parameter);
 }
 
+/*!
+ * Returns the list of parameters used by the effect.
+ */
 QVector<QParameter *> QEffect::parameters() const
 {
     Q_D(const QEffect);
@@ -118,9 +149,7 @@ QVector<QParameter *> QEffect::parameters() const
 }
 
 /*!
- * Adds a new technique \a t to the effect. This posts a CommponentAdded
- * QScenePropertyChange notification to the QChangeArbiter, the value is
- * the added technique and the property name is "technique".
+ * Adds a new technique \a t to the effect. It sends a QPropertyNodeAddedChange to the backend.
  */
 void QEffect::addTechnique(QTechnique *t)
 {
@@ -148,9 +177,7 @@ void QEffect::addTechnique(QTechnique *t)
 }
 
 /*!
- * Removes a technique \a t from the effect. This posts a ComponentRemoved
- * QScenePropertyChange notification to the QChangeArbiter, the value is
- * the removed technique's id and the property name is "technique".
+ * Removes a technique \a t from the effect.
  */
 void QEffect::removeTechnique(QTechnique *t)
 {
diff --git a/src/render/materialsystem/qfilterkey.cpp b/src/render/materialsystem/qfilterkey.cpp
index edf96314c..d4bc26515 100644
--- a/src/render/materialsystem/qfilterkey.cpp
+++ b/src/render/materialsystem/qfilterkey.cpp
@@ -56,20 +56,20 @@ QFilterKeyPrivate::QFilterKeyPrivate()
     \class Qt3DRender::QFilterKey
     \inmodule Qt3DRender
     \since 5.5
-    \brief The QFilterKey class provides ...
+    \brief The QFilterKey class provides storage for filter keys and their values
 */
 
 /*!
-    \qmltype Annotation
+    \qmltype FilterKey
     \instantiates Qt3DRender::QFilterKey
     \inherits Node
     \inqmlmodule Qt3D.Render
     \since 5.5
-    \brief For annotating ...
+    \brief For storing filter keys and their value
 */
 
 /*!
-  The constructor creats a new annotation under \a parent.
+  The constructor creates a new QFilterKey under \a parent.
  */
 QFilterKey::QFilterKey(QNode *parent)
     : QNode(*new QFilterKeyPrivate, parent)
@@ -101,11 +101,12 @@ void QFilterKey::setName(const QString &name)
 
 /*!
   \property QFilterKey::value
-
+    Specifies the value of the filter key
 */
 
 /*!
   \qmlproperty variant Qt3D.Render::Annotation::value
+    Specifies the value of the filter key
 */
 
 QVariant QFilterKey::value() const
@@ -116,11 +117,12 @@ QVariant QFilterKey::value() const
 
 /*!
   \property QFilterKey::name
-
+    Specifies the name of the filter key
  */
 
 /*!
   \qmlproperty string Qt3D.Render::Annotation::name
+    Specifies the name of the filter key
  */
 
 QString QFilterKey::name() const
diff --git a/src/render/materialsystem/qmaterial.cpp b/src/render/materialsystem/qmaterial.cpp
index fa4955017..b116b57dd 100644
--- a/src/render/materialsystem/qmaterial.cpp
+++ b/src/render/materialsystem/qmaterial.cpp
@@ -52,19 +52,19 @@
  * \instantiates Qt3DRender::QMaterial
  * \inqmlmodule Qt3D.Render
  * \brief Non-creatable abstract base for materials.
+ * \inherits Component
  */
 
 /*!
  * \class Qt3DRender::QMaterial
  * \inmodule Qt3DRender
  *
- * \inherits Component
  *
  * \brief Provides an abstract class that should be the base of all
  * Material component classes in a scene.
  *
- * QAbstractMaterial provide a way to specify the rendering of an Entity.
- * Any aspect can define its own subclass of QAbstractMaterial so that a
+ * QMaterial provides a way to specify the rendering of an Entity.
+ * Any aspect can define its own subclass of QMaterial so that a
  * Material can be used to describe a visual element; for example, the way
  * sound should reflect off an element, the temperature of a surface,
  * and so on.
@@ -88,6 +88,10 @@ QMaterialPrivate::~QMaterialPrivate()
 {
 }
 
+/*!
+  \fn Qt3DRender::QMaterial::QMaterial(Qt3DCore::QNode *parent)
+  Constructs a new QMaterial with the specified \a parent.
+ */
 QMaterial::QMaterial(QNode *parent)
     : QComponent(*new QMaterialPrivate, parent)
 {
@@ -105,6 +109,15 @@ QMaterial::QMaterial(QMaterialPrivate &dd, QNode *parent)
 }
 
 /*!
+  \qmlproperty QEffect Qt3D.Render::Material::effect
+    Specifies the effect to be used with the material
+*/
+
+/*!
+  \property Qt3DRender::QMaterial::effect
+    Specifies the effect to be used with the material
+ */
+/*!
  * Sets the \a effect to be used with the Material.
  */
 void QMaterial::setEffect(QEffect *effect)
@@ -140,6 +153,9 @@ QEffect *QMaterial::effect() const
     return d->m_effect;
 }
 
+/*!
+ * Add a parameter to the Material.
+ */
 void QMaterial::addParameter(QParameter *parameter)
 {
     Q_ASSERT(parameter);
@@ -165,6 +181,9 @@ void QMaterial::addParameter(QParameter *parameter)
     }
 }
 
+/*!
+ * Remove a parameter from the Material.
+ */
 void QMaterial::removeParameter(QParameter *parameter)
 {
     Q_ASSERT(parameter);
@@ -177,6 +196,9 @@ void QMaterial::removeParameter(QParameter *parameter)
     d->m_parameters.removeOne(parameter);
 }
 
+/*!
+ * Returns a vector of the materials current parameters
+ */
 QVector<QParameter *> QMaterial::parameters() const
 {
     Q_D(const QMaterial);
diff --git a/src/render/materialsystem/qparameter.cpp b/src/render/materialsystem/qparameter.cpp
index ae5981f5e..c9ef6c0d2 100644
--- a/src/render/materialsystem/qparameter.cpp
+++ b/src/render/materialsystem/qparameter.cpp
@@ -43,6 +43,21 @@
 #include <Qt3DCore/qpropertyupdatedchange.h>
 #include <Qt3DRender/qtexture.h>
 
+
+/*!
+ * \qmltype Parameter
+ * \instantiates Qt3DRender::QParameter
+ * \inqmlmodule Qt3D.Render
+ * \brief Provides storage for a name and value pair.
+ */
+
+/*!
+ * \class Qt3DRender::QParameter
+ * \inmodule Qt3DRender
+ *
+ * \brief Provides storage for a name and value pair.
+ */
+
 QT_BEGIN_NAMESPACE
 
 using namespace Qt3DCore;
@@ -70,11 +85,19 @@ QParameter::QParameter(QParameterPrivate &dd, QNode *parent)
 {
 }
 
+/*!
+  \fn Qt3DRender::QParameter::QParameter(Qt3DCore::QNode *parent)
+  Constructs a new QParameter with the specified \a parent.
+ */
 QParameter::QParameter(QNode *parent)
     : QNode(*new QParameterPrivate, parent)
 {
 }
 
+/*!
+  \fn Qt3DRender::QParameter::QParameter(Qt3DCore::QNode *parent)
+  Constructs a new QParameter with the specified \a parent \a name and \a value.
+ */
 QParameter::QParameter(const QString &name, const QVariant &value, QNode *parent)
     : QNode(*new QParameterPrivate, parent)
 {
@@ -83,6 +106,10 @@ QParameter::QParameter(const QString &name, const QVariant &value, QNode *parent
     setValue(value);
 }
 
+/*!
+  \fn Qt3DRender::QParameter::QParameter(Qt3DCore::QNode *parent)
+  Constructs a new QParameter with the specified \a parent \a name and takes its value from \a texture.
+ */
 QParameter::QParameter(const QString &name, QAbstractTexture *texture, QNode *parent)
     : QNode(*new QParameterPrivate, parent)
 {
@@ -96,6 +123,15 @@ QParameter::~QParameter()
 {
 }
 
+/*!
+  \qmlproperty QString Qt3D.Render::Parameter::name
+    Specifies the name of the parameter
+*/
+
+/*!
+  \property Qt3DRender::QParameter::name
+    Specifies the name of the parameter
+ */
 void QParameter::setName(const QString &name)
 {
     Q_D(QParameter);
@@ -111,6 +147,15 @@ QString QParameter::name() const
     return d->m_name;
 }
 
+/*!
+  \qmlproperty QVariant Qt3D.Render::Parameter::value
+    Specifies the value of the parameter
+*/
+
+/*!
+  \property Qt3DRender::QParameter::value
+    Specifies the value of the parameter
+ */
 void QParameter::setValue(const QVariant &dv)
 {
     Q_D(QParameter);
diff --git a/src/render/materialsystem/qrenderpass.cpp b/src/render/materialsystem/qrenderpass.cpp
index 9ec7a452b..8043681c7 100644
--- a/src/render/materialsystem/qrenderpass.cpp
+++ b/src/render/materialsystem/qrenderpass.cpp
@@ -59,7 +59,26 @@ QRenderPassPrivate::QRenderPassPrivate()
     , m_shader(nullptr)
 {
 }
+/*!
+ * \qmltype RenderPass
+ * \instantiates Qt3DRender::QRenderPass
+ * \inqmlmodule Qt3D.Render
+ * \brief Encapsulates a Render Pass.
+ */
+
+/*!
+ * \class Qt3DRender::QRenderPass
+ * \inmodule Qt3DRender
+ *
+ * \inherits Node
+ *
+ * \brief Encapsulates a Render Pass.
+ */
 
+/*!
+  \fn Qt3DRender::QRenderPass::QRenderPass(Qt3DCore::QNode *parent)
+  Constructs a new QRenderPass with the specified \a parent.
+ */
 QRenderPass::QRenderPass(QNode *parent)
     : QNode(*new QRenderPassPrivate, parent)
 {
@@ -77,9 +96,16 @@ QRenderPass::QRenderPass(QRenderPassPrivate &dd, QNode *parent)
 }
 
 /*!
- * Sets the pass's \a shaderProgram. This posts a ComponentUpdated
- * QScenePropertyChange to the QChangeArbiter. The value is set to
- * the \a shaderProgram and the property name to \c {"shaderProgram"}.
+  \qmlproperty ShaderProgram Qt3D.Render::RenderPass::shaderProgram
+    Specifies the shader program to be used for this render pass
+*/
+
+/*!
+  \property Qt3DRender::QRenderPass::shaderProgram
+    Specifies the shader program to be used for this render pass
+ */
+/*!
+ * Sets the pass's \a shaderProgram.
  */
 void QRenderPass::setShaderProgram(QShaderProgram *shaderProgram)
 {
@@ -118,6 +144,9 @@ QShaderProgram *QRenderPass::shaderProgram() const
     return d->m_shader;
 }
 
+/*!
+ * Adds \a filterKey from to the Qt3DRender::QRenderPass local filter keys.
+ */
 void QRenderPass::addFilterKey(QFilterKey *filterKey)
 {
     Q_ASSERT(filterKey);
@@ -143,6 +172,9 @@ void QRenderPass::addFilterKey(QFilterKey *filterKey)
     }
 }
 
+/*!
+ * Removes \a filterKey from the Qt3DRender::QRenderPass local filter keys.
+ */
 void QRenderPass::removeFilterKey(QFilterKey *filterKey)
 {
     Q_ASSERT(filterKey);
@@ -157,6 +189,10 @@ void QRenderPass::removeFilterKey(QFilterKey *filterKey)
     d->unregisterDestructionHelper(filterKey);
 }
 
+/*!
+ * Returns the list of Qt3DCore::QFilterKey key objects making up the filter keys
+ * of the Qt3DRender::QRenderPass.
+ */
 QVector<QFilterKey *> QRenderPass::filterKeys() const
 {
     Q_D(const QRenderPass);
@@ -219,6 +255,9 @@ QVector<QRenderState *> QRenderPass::renderStates() const
     return d->m_renderStates;
 }
 
+/*!
+ * Add a parameter to the Render Pass.
+ */
 void QRenderPass::addParameter(QParameter *parameter)
 {
     Q_ASSERT(parameter);
@@ -244,6 +283,9 @@ void QRenderPass::addParameter(QParameter *parameter)
     }
 }
 
+/*!
+ * Remove a parameter from the  Render Pass.
+ */
 void QRenderPass::removeParameter(QParameter *parameter)
 {
     Q_ASSERT(parameter);
@@ -258,7 +300,9 @@ void QRenderPass::removeParameter(QParameter *parameter)
     d->unregisterDestructionHelper(parameter);
 }
 
-
+/*!
+ * Returns a vector of the render pass's current parameters
+ */
 QVector<QParameter *> QRenderPass::parameters() const
 {
     Q_D(const QRenderPass);