1 files changed, 118 insertions, 9 deletions

diff --git a/src/render/materialsystem/qparameter.cpp b/src/render/materialsystem/qparameter.cpp
index 8f83fd02e..2ca7d176b 100644
--- a/src/render/materialsystem/qparameter.cpp
+++ b/src/render/materialsystem/qparameter.cpp
@@ -45,18 +45,127 @@
 
 
 /*!
- * \qmltype Parameter
- * \instantiates Qt3DRender::QParameter
- * \inqmlmodule Qt3D.Render
- * \brief Provides storage for a name and value pair.
+    \qmltype Parameter
+    \instantiates Qt3DRender::QParameter
+    \inqmlmodule Qt3D.Render
+    \brief Provides storage for a name and value pair. This maps to a shader uniform.
+
+    A Parameter can be referenced by a RenderPass, Technique, Effect, Material,
+    TechniqueFilter, RenderPassFilter. At runtime, depending on which shader is
+    selected for a given step of the rendering, the value contained in a
+    Parameter will be converted and uploaded if the shader contains a uniform
+    with a name matching that of the Parameter.
+
+    \code
+    Parameter {
+        name: "diffuseColor"
+        value: "blue"
+    }
+
+    // Works with the following GLSL uniform shader declarations
+    // uniform vec4 diffuseColor;
+    // uniform vec3 diffuseColor;
+    // uniform vec2 diffuseColor;
+    // uniform float diffuseColor;
+    \endcode
+
+    \note some care must be taken to ensure the value wrapped by a Parameter
+    can actually be converted to what the real uniform expect. Giving a value
+    stored as an int where the actual shader uniform is of type float could
+    result in undefined behaviors.
+
+    \note when the targeted uniform is an array, the name should be the name
+    of the uniform with [0] appended to it.
+
+    \code
+    Parameter {
+        name: "diffuseValues[0]"
+        value: [0.0, 1.0. 2.0, 3.0, 4.0, 883.0, 1340.0, 1584.0]
+    }
+
+    // Matching GLSL shader uniform  declaration
+    // uniform float diffuseValues[8];
+    \endcode
+
+    When it comes to texture support, the Parameter value should be set to the
+    appropriate Texture subclass that matches the sampler type of the shader
+    uniform.
+
+    \code
+    Parameter {
+        name: "diffuseTexture"
+        value: Texture2D { ... }
+    }
+
+    // Works with the following GLSL uniform shader declaration
+    // uniform sampler2D diffuseTexture
+    \endcode
+
+    \sa Texture
  */
 
 /*!
- * \class Qt3DRender::QParameter
- * \inheaderfile Qt3DRender/QParameter
- * \inmodule Qt3DRender
- *
- * \brief Provides storage for a name and value pair.
+    \class Qt3DRender::QParameter
+    \inheaderfile Qt3DRender/QParameter
+    \inmodule Qt3DRender
+    \brief Provides storage for a name and value pair. This maps to a shader uniform.
+
+    A QParameter can be referenced by a QRenderPass, QTechnique, QEffect, QMaterial,
+    QTechniqueFilter, QRenderPassFilter. At runtime, depending on which shader is
+    selected for a given step of the rendering, the value contained in a
+    QParameter will be converted and uploaded if the shader contains a uniform
+    with a name matching that of the QParameter.
+
+    \code
+    QParameter *param = new QParameter();
+    param->setName(QStringLiteral("diffuseColor"));
+    param->setValue(QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));
+
+    // Alternatively you can create and set a QParameter this way
+    QParameter *param2 = new QParameter(QStringLiteral("diffuseColor"), QColor::fromRgbF(0.0f, 0.0f, 1.0f, 1.0f));
+
+    // Such QParameters will work with the following GLSL uniform shader declarations
+    // uniform vec4 diffuseColor;
+    // uniform vec3 diffuseColor;
+    // uniform vec2 diffuseColor;
+    // uniform float diffuseColor;
+    \endcode
+
+    \note some care must be taken to ensure the value wrapped by a QParameter
+    can actually be converted to what the real uniform expect. Giving a value
+    stored as an int where the actual shader uniform is of type float could
+    result in undefined behaviors.
+
+    \note when the targeted uniform is an array, the name should be the name
+    of the uniform with [0] appended to it.
+
+    \code
+    QParameter *param = new QParameter();
+    QVariantList values = QVariantList() << 0.0f << 1.0f << 2.0f << 3.0f << 4.0f << 883.0f << 1340.0f << 1584.0f;
+
+    param->setName(QStringLiteral("diffuseValues[0]"));
+    param->setValue(values);
+
+    // Matching GLSL shader uniform  declaration
+    // uniform float diffuseValues[8];
+    \endcode
+
+    When it comes to texture support, the QParameter value should be set to the
+    appropriate QAbstractTexture subclass that matches the sampler type of the shader
+    uniform.
+
+    \code
+    QTexture2D *texture = new QTexture2D();
+    ...
+    QParameter *param = new QParameter();
+    param->setName(QStringLiteral("diffuseTexture"));
+    param->setValue(QVariant::fromValue(texture));
+
+    // Works with the following GLSL uniform shader declaration
+    // uniform sampler2D diffuseTexture
+    \endcode
+
+    \sa QAbstractTexture
  */
 
 QT_BEGIN_NAMESPACE