Doc: Add note about implementation specific property meaning

Fixes: QTBUG-73095
Change-Id: I843b0376ed0e4ece6ef949acb596a0303aac977d
Reviewed-by: Andy Shaw <andy.shaw@qt.io>

4 files changed, 84 insertions, 18 deletions

diff --git a/src/render/lights/qdirectionallight.cpp b/src/render/lights/qdirectionallight.cpp
index 13fb78843..51827b644 100644
--- a/src/render/lights/qdirectionallight.cpp
+++ b/src/render/lights/qdirectionallight.cpp
@@ -115,12 +115,18 @@ QDirectionalLight::QDirectionalLight(QDirectionalLightPrivate &dd, QNode *parent
 
 /*!
   \qmlproperty vector3d Qt3D.Render::DirectionalLight::worldDirection
-    Specifies the world direction of the directional light
+    Specifies the world direction of the directional light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QDirectionalLight::worldDirection
-    Specifies the world direction of the directional light
+    Specifies the world direction of the directional light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 void QDirectionalLight::setWorldDirection(const QVector3D &direction)
 {
diff --git a/src/render/lights/qenvironmentlight.cpp b/src/render/lights/qenvironmentlight.cpp
index 86ef04f95..977e117db 100644
--- a/src/render/lights/qenvironmentlight.cpp
+++ b/src/render/lights/qenvironmentlight.cpp
@@ -158,6 +158,9 @@ QEnvironmentLight::~QEnvironmentLight()
     Holds the current environment irradiance map texture.
 
     By default, the environment irradiance texture is null.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
@@ -166,6 +169,9 @@ QEnvironmentLight::~QEnvironmentLight()
     Holds the current environment irradiance map texture.
 
     By default, the environment irradiance texture is null.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 QAbstractTexture *QEnvironmentLight::irradiance() const
 {
@@ -179,6 +185,9 @@ QAbstractTexture *QEnvironmentLight::irradiance() const
     Holds the current environment specular map texture.
 
     By default, the environment specular texture is null.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
@@ -187,6 +196,9 @@ QAbstractTexture *QEnvironmentLight::irradiance() const
     Holds the current environment specular map texture.
 
     By default, the environment specular texture is null.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 QAbstractTexture *QEnvironmentLight::specular() const
 {
diff --git a/src/render/lights/qpointlight.cpp b/src/render/lights/qpointlight.cpp
index 2b042c91d..c16291709 100644
--- a/src/render/lights/qpointlight.cpp
+++ b/src/render/lights/qpointlight.cpp
@@ -135,12 +135,18 @@ QPointLight::QPointLight(QPointLightPrivate &dd, QNode *parent)
 
 /*!
   \qmlproperty float Qt3D.Render::PointLight::constantAttenuation
-    Specifies the constant attenuation of the point light
+    Specifies the constant attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QPointLight::constantAttenuation
-    Specifies the constant attenuation of the point light
+    Specifies the constant attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QPointLight::constantAttenuation() const
 {
@@ -159,12 +165,18 @@ void QPointLight::setConstantAttenuation(float value)
 
 /*!
   \qmlproperty float Qt3D.Render::PointLight::linearAttenuation
-    Specifies the linear attenuation of the point light
+    Specifies the linear attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QPointLight::linearAttenuation
-    Specifies the linear attenuation of the point light
+    Specifies the linear attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QPointLight::linearAttenuation() const
 {
@@ -183,12 +195,18 @@ void QPointLight::setLinearAttenuation(float value)
 
 /*!
   \qmlproperty float Qt3D.Render::PointLight::quadraticAttenuation
-    Specifies the quadratic attenuation of the point light
+    Specifies the quadratic attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QPointLight::quadraticAttenuation
-    Specifies the quadratic attenuation of the point light
+    Specifies the quadratic attenuation of the point light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QPointLight::quadraticAttenuation() const
 {
diff --git a/src/render/lights/qspotlight.cpp b/src/render/lights/qspotlight.cpp
index eddafbe61..c725a6baf 100644
--- a/src/render/lights/qspotlight.cpp
+++ b/src/render/lights/qspotlight.cpp
@@ -140,12 +140,18 @@ QSpotLight::QSpotLight(QSpotLightPrivate &dd, QNode *parent)
 
 /*!
   \qmlproperty float Qt3D.Render::SpotLight::constantAttenuation
-    Specifies the constant attenuation of the spot light
+    Specifies the constant attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QSpotLight::constantAttenuation
-    Specifies the constant attenuation of the spot light
+    Specifies the constant attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QSpotLight::constantAttenuation() const
 {
@@ -164,12 +170,18 @@ void QSpotLight::setConstantAttenuation(float value)
 
 /*!
   \qmlproperty float Qt3D.Render::SpotLight::linearAttenuation
-    Specifies the linear attenuation of the spot light
+    Specifies the linear attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QSpotLight::linearAttenuation
-    Specifies the linear attenuation of the spot light
+    Specifies the linear attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QSpotLight::linearAttenuation() const
 {
@@ -188,12 +200,18 @@ void QSpotLight::setLinearAttenuation(float value)
 
 /*!
   \qmlproperty float Qt3D.Render::SpotLight::quadraticAttenuation
-    Specifies the quadratic attenuation of the spot light
+    Specifies the quadratic attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QSpotLight::quadraticAttenuation
-    Specifies the quadratic attenuation of the spot light
+    Specifies the quadratic attenuation of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QSpotLight::quadraticAttenuation() const
 {
@@ -212,12 +230,18 @@ void QSpotLight::setQuadraticAttenuation(float value)
 
 /*!
   \qmlproperty vector3d Qt3D.Render::SpotLight::localDirection
-    Specifies the local direction of the spot light
+    Specifies the local direction of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QSpotLight::localDirection
-    Specifies the local direction of the spot light
+    Specifies the local direction of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 QVector3D QSpotLight::localDirection() const
 {
@@ -227,12 +251,18 @@ QVector3D QSpotLight::localDirection() const
 
 /*!
   \qmlproperty float Qt3D.Render::SpotLight::cutOffAngle
-    Specifies the cut off angle of the spot light
+    Specifies the cut off angle of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
 */
 
 /*!
   \property Qt3DRender::QSpotLight::cutOffAngle
-    Specifies the cut off angle of the spot light
+    Specifies the cut off angle of the spot light.
+
+    \note The exact meaning and use of this property is up to the
+          material implementation.
  */
 float QSpotLight::cutOffAngle() const
 {