Improve on scenegraph documentation.

Change-Id: Ib584a45454f6fd2a3c0bfb32a76b19839e4a2a09
Reviewed-by: Kim M. Kalland <kim.kalland@nokia.com>
Reviewed-by: Chris Adams <christopher.adams@nokia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>

6 files changed, 60 insertions, 40 deletions

diff --git a/src/quick/scenegraph/util/qsgflatcolormaterial.cpp b/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
index 50c8d1661e..8a4ce6db41 100644
--- a/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
+++ b/src/quick/scenegraph/util/qsgflatcolormaterial.cpp
@@ -119,6 +119,7 @@ const char *FlatColorMaterialShader::fragmentShader() const {
 
 /*!
     \class QSGFlatColorMaterial
+
     \brief The QSGFlatColorMaterial class provides a convenient way of rendering
     solid colored geometry in the scene graph.
 
@@ -133,7 +134,7 @@ const char *FlatColorMaterialShader::fragmentShader() const {
     set compatible with this material.
 
     The flat color material respects both current opacity and current matrix
-    when updating it's rendering state.
+    when updating its rendering state.
  */
 
 
@@ -150,7 +151,7 @@ QSGFlatColorMaterial::QSGFlatColorMaterial() : m_color(QColor(255, 255, 255))
 
 
 /*!
-    \fn QColor QSGFlatColorMaterial::color() const
+    \fn const QColor &QSGFlatColorMaterial::color() const
 
     Returns this flat color material's color.
 
@@ -192,6 +193,10 @@ QSGMaterialShader *QSGFlatColorMaterial::createShader() const
 }
 
 
+/*!
+    \internal
+ */
+
 int QSGFlatColorMaterial::compare(const QSGMaterial *other) const
 {
     const QSGFlatColorMaterial *flat = static_cast<const QSGFlatColorMaterial *>(other);
diff --git a/src/quick/scenegraph/util/qsgsimplematerial.cpp b/src/quick/scenegraph/util/qsgsimplematerial.cpp
index 38758b433a..1a25fac67f 100644
--- a/src/quick/scenegraph/util/qsgsimplematerial.cpp
+++ b/src/quick/scenegraph/util/qsgsimplematerial.cpp
@@ -42,7 +42,7 @@
 /*!
     \class QSGSimpleMaterialShader
 
-    \brief The QSGSimpleMaterialShader provides a convenient way of
+    \brief The QSGSimpleMaterialShader class provides a convenient way of
     building custom materials for the scene graph.
 
     \inmodule QtQuick
@@ -140,49 +140,63 @@
     renderer internally uses to identify this shader. For this reason,
     the unique QSGSimpleMaterialShader implemenation must be
     instantiated with a unique C++ type.
-
  */
 
 /*!
-    \fn QList<QByteArray> QSGSimpleMaterialShader::attributes() const
+    \fn char const *const *QSGSimpleMaterialShader::attributeNames() const
+    \internal
+ */
 
-    Returns a list of names, declaring the vertex attributes in the
-    vertex shader.
-*/
+/*!
+    \fn void QSGSimpleMaterialShader::initialize()
+    \internal
+ */
 
 /*!
-    \fn void QSGSimpleMaterialShader::updateState(const State *newState, const State *oldState)
+    \fn void QSGSimpleMaterialShader::resolveUniforms()
+    \internal
+ */
 
-    Called whenever the state of this shader should be updated,
-    typical for each new set of geometries being drawn.
+/*!
+    \fn const char *QSGSimpleMaterialShader::uniformMatrixName() const
+    \internal
+ */
 
-    Both the old and the new state are passed in so that the
-    implementation can compare and minimize the state changes when
-    applicable.
-*/
+/*!
+    \fn const char *QSGSimpleMaterialShader::uniformOpacityName() const
+    \internal
+ */
 
 /*!
-    \fn const char *QSGSimpleMaterialShader::vertexShader() const
+    \fn void QSGSimpleMaterialShader::updateState(const RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
+    \internal
+ */
 
-    Called when the shader is being initialized to get the vertex
-    shader source code.
 
-    The contents returned from this function should never change.
-*/
+/*!
+    \fn QList<QByteArray> QSGSimpleMaterialShader::attributes() const
 
+    Returns a list of names, declaring the vertex attributes in the
+    vertex shader.
+*/
 
 /*!
-    \fn const char *QSGSimpleMaterialShader::fragmentShader() const
+    \fn void QSGSimpleMaterialShader::updateState(const State *newState, const State *oldState)
 
-    Called when the shader is being initialized to get the vertex
-    shader source code.
+    Called whenever the state of this shader should be updated from
+    \a oldState to \a newState, typical for each new set of
+    geometries being drawn.
 
-    The contents returned from this function should never change.
+    Both the old and the new state are passed in so that the
+    implementation can compare and minimize the state changes when
+    applicable.
 */
 
 /*!
     \class QSGSimpleMaterial
 
+    \inmodule QtQuick
+
     \brief The QSGSimpleMaterial class is a template generated class
     used to store the state used with a QSGSimpleMateralShader.
 
@@ -195,8 +209,3 @@
 */
 
 
-
-
-
-
-
diff --git a/src/quick/scenegraph/util/qsgsimplematerial.h b/src/quick/scenegraph/util/qsgsimplematerial.h
index 5e58bd56ca..1dbb7eeffe 100644
--- a/src/quick/scenegraph/util/qsgsimplematerial.h
+++ b/src/quick/scenegraph/util/qsgsimplematerial.h
@@ -140,8 +140,8 @@ typedef QSGMaterialShader *(*PtrShaderCreateFunc)();
 template <typename State>
 class QSGSimpleMaterial : public QSGMaterial
 {
-
 public:
+#ifndef qdoc
     QSGSimpleMaterial(const State &state, PtrShaderCreateFunc func)
         : m_state(state)
         , m_func(func)
@@ -158,6 +158,7 @@ public:
 
     State *state() { return &m_state; }
     const State *state() const { return &m_state; }
+#endif
 
 private:
     static QSGMaterialType m_type;
diff --git a/src/quick/scenegraph/util/qsgtexture.cpp b/src/quick/scenegraph/util/qsgtexture.cpp
index a380d6ecb2..816b0416a5 100644
--- a/src/quick/scenegraph/util/qsgtexture.cpp
+++ b/src/quick/scenegraph/util/qsgtexture.cpp
@@ -592,6 +592,7 @@ void QSGPlainTexture::bind()
     \class QSGDynamicTexture
     \brief The QSGDynamicTexture class serves as a baseclass for dynamically changing textures,
     such as content that is rendered to FBO's.
+    \inmodule QtQuick
 
     To update the content of the texture, call updateTexture() explicitly. Simply calling bind()
     will not update the texture.
diff --git a/src/quick/scenegraph/util/qsgtexturematerial.cpp b/src/quick/scenegraph/util/qsgtexturematerial.cpp
index 96fc037bfe..7f461bb72d 100644
--- a/src/quick/scenegraph/util/qsgtexturematerial.cpp
+++ b/src/quick/scenegraph/util/qsgtexturematerial.cpp
@@ -164,7 +164,7 @@ void QSGOpaqueTextureMaterialShader::updateState(const RenderState &state, QSGMa
 
     The default mipmap filtering and filtering mode is set to
     QSGTexture::Nearest. The default wrap modes is set to
-    QSGTexture::ClampToEdge.
+    \c QSGTexture::ClampToEdge.
 
  */
 QSGOpaqueTextureMaterial::QSGOpaqueTextureMaterial()
@@ -236,7 +236,7 @@ void QSGOpaqueTextureMaterial::setTexture(QSGTexture *texture)
 
     Returns this material's mipmap filtering mode.
 
-    The default mipmap mode is QSGTexture::Nearest.
+    The default mipmap mode is \c QSGTexture::Nearest.
  */
 
 
@@ -253,17 +253,17 @@ void QSGOpaqueTextureMaterial::setTexture(QSGTexture *texture)
 
 
 /*!
-    \fn QSGTexture::Filtering filtering() const
+    \fn QSGTexture::Filtering QSGOpaqueTextureMaterial::filtering() const
 
     Returns this material's filtering mode.
 
-    The default filtering is QSGTexture::Nearest.
+    The default filtering is \c QSGTexture::Nearest.
  */
 
 
 
 /*!
-    \fn void setHorizontalWrapMode(QSGTexture::WrapMode mode)
+    \fn void QSGOpaqueTextureMaterial::setHorizontalWrapMode(QSGTexture::WrapMode mode)
 
     Sets the horizontal wrap mode to \a mode.
 
@@ -274,17 +274,17 @@ void QSGOpaqueTextureMaterial::setTexture(QSGTexture *texture)
 
 
  /*!
-     \fn QSGTexture::WrapMode horizontalWrapMode() const
+     \fn QSGTexture::WrapMode QSGOpaqueTextureMaterial::horizontalWrapMode() const
 
      Returns this material's horizontal wrap mode.
 
-     The default horizontal wrap mode is QSGTexutre::ClampToEdge
+     The default horizontal wrap mode is \c QSGTexutre::ClampToEdge.
   */
 
 
 
 /*!
-    \fn void setVerticalWrapMode(QSGTexture::WrapMode mode)
+    \fn void QSGOpaqueTextureMaterial::setVerticalWrapMode(QSGTexture::WrapMode mode)
 
     Sets the vertical wrap mode to \a mode.
 
@@ -295,11 +295,11 @@ void QSGOpaqueTextureMaterial::setTexture(QSGTexture *texture)
 
 
  /*!
-     \fn QSGTexture::WrapMode verticalWrapMode() const
+     \fn QSGTexture::WrapMode QSGOpaqueTextureMaterial::verticalWrapMode() const
 
      Returns this material's vertical wrap mode.
 
-     The default vertical wrap mode is QSGTexutre::ClampToEdge
+     The default vertical wrap mode is \c QSGTexutre::ClampToEdge.
   */
 
 
diff --git a/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp b/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
index 545b5f201e..1b1b35bbff 100644
--- a/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
+++ b/src/quick/scenegraph/util/qsgvertexcolormaterial.cpp
@@ -130,6 +130,10 @@ const char *QSGVertexColorMaterialShader::fragmentShader() const {
  */
 
 
+/*!
+    Creates a new vertex color material.
+ */
+
 QSGVertexColorMaterial::QSGVertexColorMaterial()
 {
     setFlag(Blending, true);