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>

12 files changed, 680 insertions, 133 deletions

diff --git a/src/quick/scenegraph/coreapi/qsgdefaultrenderer.cpp b/src/quick/scenegraph/coreapi/qsgdefaultrenderer.cpp
index f0c90e364a..26cd5c3199 100644
--- a/src/quick/scenegraph/coreapi/qsgdefaultrenderer.cpp
+++ b/src/quick/scenegraph/coreapi/qsgdefaultrenderer.cpp
@@ -153,9 +153,6 @@ void QSGDefaultRenderer::nodeChanged(QSGNode *node, QSGNode::DirtyState state)
 
     if (state & rebuildBits)
         m_rebuild_lists = true;
-
-    if (state & (rebuildBits | QSGNode::DirtyClipList))
-        m_needs_sorting = true;
 }
 
 void QSGDefaultRenderer::render()
diff --git a/src/quick/scenegraph/coreapi/qsggeometry.cpp b/src/quick/scenegraph/coreapi/qsggeometry.cpp
index c4c6c4f355..49f64d52ec 100644
--- a/src/quick/scenegraph/coreapi/qsggeometry.cpp
+++ b/src/quick/scenegraph/coreapi/qsggeometry.cpp
@@ -104,24 +104,286 @@ const QSGGeometry::AttributeSet &QSGGeometry::defaultAttributes_ColoredPoint2D()
 
 
 /*!
+    \class QSGGeometry::Attribute
+    \brief The QSGGeometry::Attribute describes a single vertex attribute in a QSGGeometry
+    \inmodule QtQuick
+
+    The QSGGeometry::Attribute struct describes the attribute register position,
+    the size of the attribute tuple and the attribute type.
+
+    It also contains a hint to the renderer if this attribute is the attribute
+    describing the position. The scene graph renderer may use this information
+    to perform optimizations.
+
+    It contains a number of bits which are reserved for future use.
+
+    \sa QSGGeometry
+ */
+
+/*!
+    \fn QSGGeometry::Attribute QSGGeometry::Attribute::create(int pos, int tupleSize, int primitiveType, bool isPosition)
+
+    Creates a new QSGGeometry::Attribute for attribute register \a pos with \a
+    tupleSize. The \a primitiveType can be any of the supported OpenGL types,
+    such as \c GL_FLOAT or \c GL_UNSIGNED_BYTE.
+
+    If the attribute describes the position for the vertex, the \a isPosition hint
+    should be set to \c true. The scene graph renderer may use this information
+    to perform optimizations.
+
+    Use the create function to construct the attribute, rather than an
+    initialization list, to ensure that all fields are initialized.
+ */
+
+
+/*!
+    \class QSGGeometry::AttributeSet
+    \brief The QSGGeometry::AttributeSet describes how the vertices in a QSGGeometry
+    are built up.
+    \inmodule QtQuick
+
+    \sa QSGGeometry
+ */
+
+
+/*!
+   \class QSGGeometry::Point2D
+   \brief The QSGGeometry::Point2D struct is a convenience struct for accessing
+   2D Points.
+
+   \inmodule QtQuick
+ */
+
+
+/*!
+   \fn void QSGGeometry::Point2D::set(float x, float y)
+
+   Sets the x and y values of this point to \a x and \a y.
+ */
+
+
+/*!
+   \class QSGGeometry::ColoredPoint2D
+   \brief The QSGGeometry::ColoredPoint2D struct is a convenience struct for accessing
+   2D Points with a color.
+
+   \inmodule QtQuick
+ */
+
+
+/*!
+   \fn void QSGGeometry::ColoredPoint2D::set(float x, float y, uchar red, uchar green, uchar blue, uchar alpha)
+
+   Sets the position of the vertex to \a x and \a y and the color to \a red, \a
+   green, \a blue, and \a alpha.
+ */
+
+
+/*!
+   \class QSGGeometry::TexturedPoint2D
+   \brief The QSGGeometry::TexturedPoint2D struct is a convenience struct for accessing
+   2D Points with texture coordinates.
+
+   \inmodule QtQuick
+ */
+
+
+/*!
+   \fn void QSGGeometry::TexturedPoint2D::set(float x, float y, float tx, float ty)
+
+   Sets the position of the vertex to \a x and \a y and the texture coordinate
+   to \a tx and \a ty.
+ */
+
+
+
+/*!
     \class QSGGeometry
-    \brief The QSGGeometry class provides low-level storage for graphics primitives
-    in the QML Scene Graph.
 
-    The QSGGeometry class provides a few convenience attributes and attribute accessors
-    by default. The defaultAttributes_Point2D() function returns attributes to be used
-    in normal solid color rectangles, while the defaultAttributes_TexturedPoint2D function
-    returns attributes to be used for the common pixmap usecase.
+    \brief The QSGGeometry class provides low-level
+    storage for graphics primitives in the \l{QML Scene Graph}.
+
+    \inmodule QtQuick
+
+    The QSGGeometry class stores the geometry of the primitives
+    rendered with the scene graph. It contains vertex data and
+    optionally index data. The mode used to draw the geometry is
+    specified with setDrawingMode(), which maps directly to the OpenGL
+    drawing mode, such as \c GL_TRIANGLE_STRIP, \c GL_TRIANGLES, or
+    \c GL_POINTS.
+
+    Vertices can be as simple as points defined by x and y values or
+    can be more complex where each vertex contains a normal, texture
+    coordinates and a 3D position. The QSGGeometry::AttributeSet is
+    used to describe how the vertex data is built up. The attribute
+    set can only be specified on construction.  The QSGGeometry class
+    provides a few convenience attributes and attribute sets by
+    default. The defaultAttributes_Point2D() function returns an
+    attribute set to be used in normal solid color rectangles, while
+    the defaultAttributes_TexturedPoint2D function returns attributes
+    to be used for textured 2D geometry. The vertex data is internally
+    stored as a \c {void *} and is accessible with the vertexData()
+    function. Convenience accessors for the common attribute sets are
+    availble with vertexDataAsPoint2D() and
+    vertexDataAsTexturedPoint2D(). Vertex data is allocated by passing
+    a vertex count to the constructor or by calling allocate() later.
+
+    The QSGGeometry can optionally contain indices of either unsigned
+    32-bit, unsigned 16-bit, or unsigned 8-bit integers. The index type
+    must be specified during construction and cannot be changed.
+
+    Below is a snippet illustrating how a geometry composed of
+    position and color vertices can be built.
+
+    \code
+    struct MyPoint2D {
+        float x;
+        float y;
+        float r;
+        float g;
+        float b;
+        float a;
+
+        void set(float x_, float y_, float r_, float g_, float b_, float a_) {
+            x = x_;
+            y = y_;
+            r = r_;
+            g = g_;
+            b = b_;
+            a = a_;
+        }
+    };
+
+    QSGGeometry::Attribute MyPoint2D_Attributes[] = {
+        QSGGeometry::Attribute::create(0, 2, GL_FLOAT, true),
+        QSGGeometry::Attribute::create(1, 4, GL_FLOAT, false)
+    };
+
+    QSGGeometry::AttributeSet MyPoint2D_AttributeSet = {
+        2,
+        sizeof(MyPoint2D),
+        MyPoint2D_Attributes
+    };
+
+    ...
+
+    geometry = new QSGGeometry(MyPoint2D_AttributeSet, 2);
+    geometry->setDrawingMode(GL_LINES);
+
+    MyPoint2D *vertices = static_cast<MyPoint2D *>(geometry->vertexData());
+    vertices[0].set(0, 0, 1, 0, 0, 1);
+    vertices[1].set(width(), height(), 0, 0, 1, 1);
+    \endcode
+
+    The QSGGeometry is a software buffer and client-side in terms of
+    OpenGL rendering, as the buffers used in 2D graphics typically consist of
+    many small buffers that change every frame and do not benefit from
+    being uploaded to graphics memory. However, the QSGGeometry
+    supports hinting to the renderer that a buffer should be
+    uploaded using the setVertexDataPattern() and
+    setIndexDataPattern() functions. Whether this hint is respected or
+    not is implementation specific.
+
+    \sa QSGGeometryNode
+
+ */
+
+/*!
+    \fn int QSGGeometry::attributeCount() const
+
+    Returns the number of attributes in the attrbute set used by this geometry.
+ */
+
+/*!
+    \fn QSGGeometry::Attribute *QSGGeometry::attributes() const
+
+    Returns an array with the attributes of this geometry. The size of the array
+    is given with attributeCount().
+ */
+
+/*!
+    \fn uint *QSGGeometry::indexDataAsUInt()
+
+    Convenience function to access the index data as a mutable array of
+    32-bit unsigned integers.
+ */
+
+/*!
+    \fn const uint *QSGGeometry::indexDataAsUInt() const
+
+    Convenience function to access the index data as an immutable array of
+    32-bit unsigned integers.
+ */
+
+/*!
+    \fn quint16 *QSGGeometry::indexDataAsUShort()
+
+    Convenience function to access the index data as a mutable array of
+    16-bit unsigned integers.
+ */
+
+/*!
+    \fn const quint16 *QSGGeometry::indexDataAsUShort() const
+
+    Convenience function to access the index data as an immutable array of
+    16-bit unsigned integers.
+ */
+
+/*!
+    \fn const QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D() const
+
+    Convenience function to access the vertex data as an immuatble
+    array of QSGGeometry::ColoredPoint2D.
+ */
+
+/*!
+    \fn QSGGeometry::ColoredPoint2D *QSGGeometry::vertexDataAsColoredPoint2D()
+
+    Convenience function to access the vertex data as a muatble
+    array of QSGGeometry::ColoredPoint2D.
+ */
+
+/*!
+    \fn const QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D() const
+
+    Convenience function to access the vertex data as an immuatble
+    array of QSGGeometry::TexturedPoint2D.
+ */
+
+/*!
+    \fn QSGGeometry::TexturedPoint2D *QSGGeometry::vertexDataAsTexturedPoint2D()
+
+    Convenience function to access the vertex data as a muatble
+    array of QSGGeometry::TexturedPoint2D.
+ */
+
+/*!
+    \fn const QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D() const
+
+    Convenience function to access the vertex data as an immuatble
+    array of QSGGeometry::Point2D.
+ */
+
+/*!
+    \fn QSGGeometry::Point2D *QSGGeometry::vertexDataAsPoint2D()
+
+    Convenience function to access the vertex data as a muatble
+    array of QSGGeometry::Point2D.
  */
 
 
 /*!
     Constructs a geometry object based on \a attributes.
 
-    The object allocate space for \a vertexCount vertices based on the accumulated
-    size in \a attributes and for \a indexCount.
+    The object allocate space for \a vertexCount vertices based on the
+    accumulated size in \a attributes and for \a indexCount.
 
-    Geometry objects are constructed with GL_TRIANGLE_STRIP as default drawing mode.
+    The \a indexType maps to the OpenGL index type and can be
+    \c GL_UNSIGNED_SHORT and \c GL_UNSIGNED_BYTE. On OpenGL implementations that
+    support it, such as desktop OpenGL, \c GL_UNSIGNED_INT can also be used.
+
+    Geometry objects are constructed with \c GL_TRIANGLE_STRIP as default
+    drawing mode.
 
     The attribute structure is assumed to be POD and the geometry object
     assumes this will not go away. There is no memory management involved.
@@ -179,9 +441,13 @@ QSGGeometry::QSGGeometry(const QSGGeometry::AttributeSet &attributes,
 
     Returns the byte size of the index type.
 
-    This value is either 1 when index type is GL_UNSIGNED_BYTE or 2 when
-    index type is GL_UNSIGNED_SHORT. For Desktop OpenGL, GL_UNSIGNED_INT
-    with the value 4 is also supported.
+    This value is either \c 1 when index type is \c GL_UNSIGNED_BYTE or \c 2
+    when index type is \c GL_UNSIGNED_SHORT. For Desktop OpenGL,
+    \c GL_UNSIGNED_INT with the value \c 4 is also supported.
+ */
+
+/*!
+    Destroys the geometry object and the vertex and index data it has allocated.
  */
 
 QSGGeometry::~QSGGeometry()
@@ -212,7 +478,7 @@ QSGGeometry::~QSGGeometry()
 
     Returns a pointer to the raw vertex data of this geometry object.
 
-    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
+    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D()
  */
 
 /*!
@@ -220,7 +486,7 @@ QSGGeometry::~QSGGeometry()
 
     Returns a pointer to the raw vertex data of this geometry object.
 
-    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D
+    \sa vertexDataAsPoint2D(), vertexDataAsTexturedPoint2D()
  */
 
 /*!
@@ -248,9 +514,9 @@ const void *QSGGeometry::indexData() const
 }
 
 /*!
-    Sets the drawing mode to be used for this geometry.
+    Sets the \a mode to be used for drawing this geometry.
 
-    The default value is GL_TRIANGLE_STRIP.
+    The default value is \c GL_TRIANGLE_STRIP.
  */
 void QSGGeometry::setDrawingMode(GLenum mode)
 {
@@ -261,7 +527,7 @@ void QSGGeometry::setDrawingMode(GLenum mode)
     Gets the current line width to be used for this geometry. This property only
     applies where the drawingMode is GL_LINES or a related value.
 
-    The default value is 1.0
+    The default value is \c 1.0
 
     \sa setLineWidth(), drawingMode()
 */
@@ -271,14 +537,14 @@ float QSGGeometry::lineWidth() const
 }
 
 /*!
-    Sets the line width to be used for this geometry. This property only applies
-    where the drawingMode is GL_LINES or a related value.
+    Sets the line width to be used for this geometry to \a width. The line width
+    only applies where the drawingMode is \c GL_LINES or a related value.
 
     \sa lineWidth(), drawingMode()
 */
-void QSGGeometry::setLineWidth(float w)
+void QSGGeometry::setLineWidth(float width)
 {
-    m_line_width = w;
+    m_line_width = width;
 }
 
 /*!
@@ -286,7 +552,7 @@ void QSGGeometry::setLineWidth(float w)
 
     Returns the drawing mode of this geometry.
 
-    The default value is GL_TRIANGLE_STRIP.
+    The default value is \c GL_TRIANGLE_STRIP.
  */
 
 /*!
@@ -403,20 +669,27 @@ void QSGGeometry::updateTexturedRectGeometry(QSGGeometry *g, const QRectF &rect,
 /*!
     \enum QSGGeometry::DataPattern
 
-    The DataPattern enum is used to specify the use pattern for the vertex
-    and index data in a geometry object.
+    The DataPattern enum is used to specify the use pattern for the
+    vertex and index data in a geometry object.
+
+    \value AlwaysUploadPattern The data is always uploaded. This means
+    that the user does not need to explicitly mark index and vertex
+    data as dirty after changing it. This is the default.
 
-    \value AlwaysUploadPattern The data is always uploaded. This means that
-    the user does not need to explicitly mark index and vertex data as
-    dirty after changing it. This is the default.
+    \value DynamicPattern The data is modified repeatedly and drawn
+    many times.  This is a hint that may provide better
+    performance. When set the user must make sure to mark the data as
+    dirty after changing it.
 
-    \value DynamicPattern The data is modified repeatedly and drawn many times.
-    This is a hint that may provide better performance. When set
-    the user must make sure to mark the data as dirty after changing it.
+    \value StaticPattern The data is modified once and drawn many
+    times. This is a hint that may provide better performance. When
+    set the user must make sure to mark the data as dirty after
+    changing it.
 
-    \value StaticPattern The data is modified once and drawn many times. This is
-    a hint that may provide better performance. When set the user must make sure
-    to mark the data as dirty after changing it.
+    \value StreamPattern The data is modified for almost every time it
+    is drawn. This is a hint that may provide better performance. When
+    set, the user must make sure to mark the data as dirty after
+    changing it.
  */
 
 
diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
index 850db69948..c67b98b875 100644
--- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp
+++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
@@ -49,6 +49,7 @@ QT_BEGIN_NAMESPACE
     \class QSGMaterialShader
     \brief The QSGMaterialShader class represents an OpenGL shader program
     in the renderer.
+    \inmodule QtQuick
 
     The QSGMaterialShader API is very low-level. A more convenient API, which
     provides almost all the same features, is available through
@@ -60,9 +61,9 @@ QT_BEGIN_NAMESPACE
     to render that material, such as a shader to flat coloring of geometry.
     Each QSGGeometryNode can have a unique QSGMaterial containing the
     how the shader should be configured when drawing that node, such as
-    the actual color to used to render the geometry.
+    the actual color used to render the geometry.
 
-    An instance of QSGMaterialShader is never created explicitely by the user,
+    An instance of QSGMaterialShader is never created explicitly by the user,
     it will be created on demand by the scene graph through
     QSGMaterial::createShader(). The scene graph will make sure that there
     is only one instance of each shader implementation through a scene graph.
@@ -154,15 +155,58 @@ QSGMaterialShader::QSGMaterialShader()
 {
 }
 
+/*!
+    \fn QSGMaterialShader::~QSGMaterialShader()
+    \internal
+ */
+
+/*!
+    \fn char const *const *QSGMaterialShader::attributeNames() const
+
+    Returns a zero-terminated array describing the names of the
+    attributes used in the vertex shader.
+
+    This function is called when the shader is compiled to specify
+    which attributes exist. The order of the attribute names
+    defines the attribute register position in the vertex shader.
+ */
+
+
+/*!
+    \fn const char *QSGMaterialShader::vertexShader() const
+
+    Called when the shader is being initialized to get the vertex
+    shader source code.
+
+    The contents returned from this function should never change.
+*/
 
 
 /*!
-    \fn QOpenGLShaderProgram *QSGMaterialShader::program() const
+   \fn const char *QSGMaterialShader::fragmentShader() const
+
+    Called when the shader is being initialized to get the fragment
+    shader source code.
+
+    The contents returned from this function should never change.
+*/
+
+
+/*!
+    \fn QOpenGLShaderProgram *QSGMaterialShader::program()
 
     Returns the shader program used by this QSGMaterialShader.
  */
 
 
+/*!
+    \fn void QSGMaterialShader::initialize()
+
+    Reimplement this function to do one-time initialization when the
+    shader program is compiled. The OpenGL shader program is compiled
+    and linked, but not bound, when this function is called.
+ */
+
 
 /*!
     This function is called by the scene graph to indicate that geometry is
@@ -304,8 +348,8 @@ void QSGMaterialShader::compile()
 /*!
     \fn bool QSGMaterialShader::RenderState::isMatrixDirty() const
 
-    Convenience function to check if the dirtyStates() indicates that the matrix
-    needs to be updated.
+    Returns \c true if the dirtyStates() contain the dirty matrix state,
+    otherwise returns \c false.
  */
 
 
@@ -313,8 +357,8 @@ void QSGMaterialShader::compile()
 /*!
     \fn bool QSGMaterialShader::RenderState::isOpacityDirty() const
 
-    Conveience function to check if the dirtyStates() indicates that the opacity
-    needs to be updated.
+    Returns \c true if the dirtyStates() contains the dirty opacity state,
+    otherwise returns \c false.
  */
 
 
@@ -330,7 +374,7 @@ void QSGMaterialShader::compile()
 
 
 /*!
-    Returns the accumulated opacity to be used for rendering
+    Returns the accumulated opacity to be used for rendering.
  */
 
 float QSGMaterialShader::RenderState::opacity() const
@@ -340,7 +384,7 @@ float QSGMaterialShader::RenderState::opacity() const
 }
 
 /*!
-    Returns the modelview determinant to be used for rendering
+    Returns the modelview determinant to be used for rendering.
  */
 
 float QSGMaterialShader::RenderState::determinant() const
@@ -434,6 +478,7 @@ static void qt_print_material_count()
 /*!
     \class QSGMaterialType
     \brief The QSGMaterialType class is used as a unique type token in combination with QSGMaterial.
+    \inmodule QtQuick
 
     It serves no purpose outside the QSGMaterial::type() function.
  */
@@ -441,6 +486,7 @@ static void qt_print_material_count()
 /*!
     \class QSGMaterial
     \brief The QSGMaterial class encapsulates rendering state for a shader program.
+    \inmodule QtQuick
 
     The QSGMaterial API is very low-level. A more convenient API, which
     provides almost all the same features, is available through
@@ -473,6 +519,10 @@ static void qt_print_material_count()
     and cannot be used from the GUI thread.
  */
 
+/*!
+    \internal
+ */
+
 QSGMaterial::QSGMaterial()
     : m_flags(0)
 {
@@ -486,6 +536,11 @@ QSGMaterial::QSGMaterial()
 #endif
 }
 
+
+/*!
+    \internal
+ */
+
 QSGMaterial::~QSGMaterial()
 {
 #ifndef QT_NO_DEBUG
@@ -510,6 +565,12 @@ QSGMaterial::~QSGMaterial()
     the full matrix of the geometry nodes for rendering.
  */
 
+/*!
+    \fn QSGMaterial::Flags QSGMaterial::flags() const
+
+    Returns the material's flags.
+ */
+
 
 
 /*!
diff --git a/src/quick/scenegraph/coreapi/qsgnode.cpp b/src/quick/scenegraph/coreapi/qsgnode.cpp
index ba0246cd37..fe4a44d858 100644
--- a/src/quick/scenegraph/coreapi/qsgnode.cpp
+++ b/src/quick/scenegraph/coreapi/qsgnode.cpp
@@ -66,33 +66,163 @@ static void qt_print_node_count()
 
     The QSGNode class can be used as a child container. Children are added with
     the appendChildNode(), prependChildNode(), insertChildNodeBefore() and
-    insertChildNodeAfter(). Ordering of nodes is important as geometry nodes
-    will be rendered in the order they are added to the scene graph.
-    Actually, the scene may reorder nodes freely, but the resulting visual
-    order is still guaranteed.
+    insertChildNodeAfter(). The order of nodes is important as geometry nodes
+    are rendered according to their ordering in the scene graph.
 
     The scene graph nodes contains a mechanism to describe which
     parts of the scene has changed. This includes the combined matrices,
-    accumulated opacity, changes to the node hierarchy, etc. This information
-    can be used for optimizations inside the scene graph renderer. For
-    the renderer to properly render the nodes, it is important that users
+    accumulated opacity, changes to the node hierarchy, and so on. This
+    information can be used for optimizations inside the scene graph renderer.
+    For the renderer to properly render the nodes, it is important that users
     call QSGNode::markDirty() with the correct flags when nodes are changed.
-    Most of the functions on the node classes will implicitly call markDirty(),
-    e.g. QSGNode::appendChildNode() will call markDirty() passing in
+    Most of the functions on the node classes will implicitly call markDirty().
+    For example, QSGNode::appendChildNode() will call markDirty() passing in
     QSGNode::DirtyNodeAdded.
 
     If nodes change every frame, the preprocess() function can be used to
-    apply changes to a node for every frame its rendered. The use of preprocess()
-    must be explicitly enabled by setting the QSGNode::UsePreprocess flag
-    on the node.
+    apply changes to a node for every frame it is rendered. The use of
+    preprocess() must be explicitly enabled by setting the
+    QSGNode::UsePreprocess flag on the node.
 
     The virtual isSubtreeBlocked() function can be used to disable a subtree all
     together. Nodes in a blocked subtree will not be preprocessed() and not
     rendered.
 
-    \warning Anything related to QSGNode should happen on the scene graph rendering thread.
+    \warning Anything related to QSGNode should happen on the scene graph
+    rendering thread.
  */
 
+/*!
+    \enum QSGNode::DirtyStateBit
+
+    Used in QSGNode::markDirty() to indicate how the scene graph has changed.
+
+    \value DirtyMatrix The matrix in a QSGTransformNode has changed.
+    \value DirtyNodeAdded A node was added.
+    \value DirtyNodeRemoved A node was removed.
+    \value DirtyGeometry The geometry of a QSGGeometryNode has changed.
+    \value DirtyMaterial The material of a QSGGeometryNode has changed.
+    \value DirtyOpacity The opacity of a QSGOpacityNode has changed.
+
+    \sa QSGNode::markDirty()
+ */
+
+/*!
+    \enum QSGNode::Flag
+
+    The QSGNode::Flag enum describes flags on the QSGNode
+
+    \value OwnedByParent The node is owned by its parent and will be deleted
+    when the parent is deleted.
+    \value UsePreprocess The node's virtual preprocess() function will be called
+    before rendering starts.
+    \value OwnsGeometry Only valid for QSGGeometryNode and QSGClipNode.
+    The node has ownership over the QSGGeometry instance and will
+    delete it when the node is destroyed.
+    \value OwnsMaterial Only valid for QSGGeometryNode. The node has ownership
+    over the material and will delete it when the node is destroyed.
+    \value OwnsOpaqueMaterial Only valid for QSGGeometryNode. The node has
+    ownership over the opaque material and will delete it when the node is
+    destroyed.
+ */
+
+/*!
+    \enum QSGNode::NodeType
+
+    Can be used to figure out the type of node.
+
+    \value BasicNodeType The type of QSGNode
+    \value GeometryNodeType The type of QSGGeometryNode
+    \value TransformNodeType The type of QSGTransformNode
+    \value ClipNodeType The type of QSGClipNode
+    \value OpacityNodeType The type of QSGOpacityNode
+
+    \sa type()
+ */
+
+/*!
+    \fn QSGNode *QSGNode::childAtIndex(int i) const
+
+    Returns the child at index \a i.
+
+    Children are stored internally as a linked list, so iterating
+    over the children via the index is suboptimal.
+ */
+
+/*!
+    \fn int QSGNode::childCount() const
+
+    Returns the number of child nodes.
+ */
+
+/*!
+    \fn void QSGNode::clearDirty()
+
+    \internal
+ */
+
+/*!
+    \fn QSGNode *QSGNode::firstChild() const
+
+    Returns the first child of this node.
+
+    The children are stored in a linked list.
+ */
+
+/*!
+    \fn QSGNode *QSGNode::lastChild() const
+
+    Returns the last child of this node.
+
+    The children are stored as a linked list.
+ */
+
+/*!
+    \fn QSGNode::Flags QSGNode::flags() const
+
+    Returns the set of flags for this node.
+ */
+
+/*!
+    \fn QSGNode *QSGNode::nextSibling() const
+
+    Returns the node after this in the parent's list of children.
+
+    The children are stored as a linked list.
+ */
+
+/*!
+    \fn QSGNode *QSGNode::previousSibling() const
+
+    Returns the node before this in the parent's list of children.
+
+    The children are stored as a linked list.
+ */
+
+/*!
+    \fn QSGNode::Type QSGNode::type() const
+
+    Returns the type of this node. The node type must be one of the
+    predefined types defined in QSGNode::NodeType and can safely be
+    used to cast to the corresponding class.
+ */
+
+/*!
+    \fn QSGNode::DirtyState QSGNode::dirtyState() const
+
+    \internal
+ */
+
+/*!
+    \fn QSGNode *QSGNode::parent() const
+
+    Returns the parent node of this node.
+ */
+
+
+/*!
+ * Constructs a new node
+ */
 QSGNode::QSGNode()
     : m_parent(0)
     , m_type(BasicNodeType)
@@ -107,6 +237,11 @@ QSGNode::QSGNode()
     init();
 }
 
+/*!
+ * Constructs a new node with the given node type.
+ *
+ * \internal
+ */
 QSGNode::QSGNode(NodeType type)
     : m_parent(0)
     , m_type(type)
@@ -121,6 +256,9 @@ QSGNode::QSGNode(NodeType type)
     init();
 }
 
+/*!
+ * \internal
+ */
 void QSGNode::init()
 {
 #ifndef QT_NO_DEBUG
@@ -133,6 +271,12 @@ void QSGNode::init()
 #endif
 }
 
+/*!
+ * Destroys the node.
+ *
+ * Every child of this node that has the flag QSGNode::OwnedByParent set,
+ * will also be deleted.
+ */
 QSGNode::~QSGNode()
 {
 #ifndef QT_NO_DEBUG
@@ -464,9 +608,9 @@ void QSGNode::setFlags(Flags f, bool enabled)
 
 
 /*!
-    Marks this node with the states in \a flags as dirty.
+    Marks this node with the states in \a bits as dirty.
 
-    When a node is marked dirty, it recursively mark the parent chain
+    When a node is marked dirty, it recursively marks the parent chain
     as dirty and notify all connected renderers that the has dirty states.
  */
 
@@ -496,7 +640,7 @@ void QSGNode::markDirty(DirtyState bits)
 
 /*!
     \class QSGBasicGeometryNode
-    \brief The QSGBasicGeometryNode class serves as a baseclass for geometry based nodes
+    \brief The QSGBasicGeometryNode class serves as a baseclass for geometry based nodes.
 
     \inmodule QtQuick
 
@@ -506,7 +650,9 @@ void QSGNode::markDirty(DirtyState bits)
 
 
 /*!
-    Creates a new basic geometry node.
+    Creates a new basic geometry node of type \a type
+
+    \internal
  */
 QSGBasicGeometryNode::QSGBasicGeometryNode(NodeType type)
     : QSGNode(type)
@@ -532,13 +678,39 @@ QSGBasicGeometryNode::~QSGBasicGeometryNode()
 
 
 /*!
-    \fn QSGGeometry *QSGBasicGeometryNode::geometry() const
+    \fn QSGGeometry *QSGBasicGeometryNode::geometry()
 
     Returns this node's geometry.
 
     The geometry is null by default.
  */
 
+/*!
+    \fn const QSGGeometry *QSGBasicGeometryNode::geometry() const
+
+    Returns this node's geometry.
+
+    The geometry is null by default.
+ */
+
+/*!
+    \fn QMatrix4x4 *QSGBasicGeometryNode::matrix() const
+
+    Will be set during rendering to contain transformation of the geometry
+    for that rendering pass.
+
+    \internal
+ */
+
+/*!
+    \fn QSGClipNode *QSGBasicGeometryNode::clipList() const
+
+    Will be set during rendering to contain the clip of the geometry
+    for that rendering pass.
+
+    \internal
+ */
+
 
 /*!
     Sets the geometry of this node to \a geometry.
@@ -549,7 +721,7 @@ QSGBasicGeometryNode::~QSGBasicGeometryNode()
     If the geometry is changed whitout calling setGeometry() again, the user
     must also mark the geometry as dirty using QSGNode::markDirty().
 
-    \sa markDirty
+    \sa markDirty()
  */
 
 void QSGBasicGeometryNode::setGeometry(QSGGeometry *geometry)
@@ -646,17 +818,42 @@ QSGGeometryNode::~QSGGeometryNode()
     \internal
  */
 
+/*!
+    \fn QSGMaterial *QSGGeometryNode::material() const
+
+    Returns the material of the QSGGeometryNode.
+
+    \sa setMaterial()
+ */
+
+/*!
+    \fn QSGMaterial *QSGGeometryNode::opaqueMaterial() const
+
+    Returns the opaque material of the QSGGeometryNode.
+
+    \sa setOpaqueMaterial()
+ */
+
+/*!
+    \fn qreal QSGGeometryNode::inheritedOpacity() const
+
+    Set during rendering to specify the inherited opacity for that
+    rendering pass.
+
+    \internal
+ */
+
 
 /*!
     Sets the render order of this node to be \a order.
 
-    GeometryNodes are rendered in an order that visually looks like
+    Geometry nodes are rendered in an order that visually looks like
     low order nodes are rendered prior to high order nodes. For opaque
     geometry there is little difference as z-testing will handle
     the discard, but for translucent objects, the rendering should
     normally be specified in the order of back-to-front.
 
-    The default render order is 0.
+    The default render order is \c 0.
 
     \internal
   */
@@ -866,6 +1063,11 @@ void QSGClipNode::setClipRect(const QRectF &rect)
     be done with some care.
  */
 
+
+/*!
+    Create a new QSGTransformNode with its matrix set to the identity matrix.
+ */
+
 QSGTransformNode::QSGTransformNode()
     : QSGNode(TransformNodeType)
 {
@@ -901,6 +1103,16 @@ void QSGTransformNode::setMatrix(const QMatrix4x4 &matrix)
     markDirty(DirtyMatrix);
 }
 
+/*!
+    \fn const QMatrix4x4 &QSGTransformNode::combinedMatrix() const
+
+    Set during rendering to the combination of all parent matrices for
+    that rendering pass.
+
+    \internal
+ */
+
+
 
 /*!
     Sets the combined matrix of this matrix to \a transform.
diff --git a/src/quick/scenegraph/coreapi/qsgnode.h b/src/quick/scenegraph/coreapi/qsgnode.h
index 7403b626e6..f0c7825531 100644
--- a/src/quick/scenegraph/coreapi/qsgnode.h
+++ b/src/quick/scenegraph/coreapi/qsgnode.h
@@ -66,15 +66,14 @@ class Q_QUICK_EXPORT QSGNode
 public:
     enum NodeType {
         BasicNodeType,
-        RootNodeType,
         GeometryNodeType,
         TransformNodeType,
         ClipNodeType,
         OpacityNodeType,
-#ifndef Q_QDOC
-        RenderNodeType, // internal
+#ifndef qdoc
+        RootNodeType,
+        RenderNodeType
 #endif
-        UserNodeType = 1024
     };
 
     enum Flag {
@@ -92,22 +91,23 @@ public:
     Q_DECLARE_FLAGS(Flags, Flag)
 
     enum DirtyStateBit {
-        DirtyUsePreprocess          = UsePreprocess,
-
         DirtyMatrix                 = 0x0100,
-        DirtyClipList               = 0x0200,
         DirtyNodeAdded              = 0x0400,
         DirtyNodeRemoved            = 0x0800,
         DirtyGeometry               = 0x1000,
         DirtyMaterial               = 0x2000,
         DirtyOpacity                = 0x4000,
+
+#ifndef qdoc
         DirtyForceUpdate            = 0x8000,
 
+        DirtyUsePreprocess          = UsePreprocess,
+
         DirtyPropagationMask        = DirtyMatrix
-                                      | DirtyClipList
                                       | DirtyNodeAdded
                                       | DirtyOpacity
                                       | DirtyForceUpdate
+#endif
 
     };
     Q_DECLARE_FLAGS(DirtyState, DirtyStateBit)
@@ -172,20 +172,9 @@ private:
     void *m_reserved;
 };
 
-Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::DirtyState)
-Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::Flags)
-
 class Q_QUICK_EXPORT QSGBasicGeometryNode : public QSGNode
 {
 public:
-//    enum  UsagePattern {
-//        Static,
-//        Dynamic,
-//        Stream
-//    };
-//    void setUsagePattern(UsagePattern pattern);
-//    UsagePattern usagePattern() const { return m_pattern; }
-
     ~QSGBasicGeometryNode();
 
     void setGeometry(QSGGeometry *geometry);
@@ -207,8 +196,6 @@ private:
 
     const QMatrix4x4 *m_matrix;
     const QSGClipNode *m_clip_list;
-
-//    UsagePattern m_pattern;
 };
 
 class QSGMaterial;
@@ -343,6 +330,9 @@ Q_QUICK_EXPORT QDebug operator<<(QDebug, const QSGRootNode *n);
 
 #endif
 
+Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::DirtyState)
+Q_DECLARE_OPERATORS_FOR_FLAGS(QSGNode::Flags)
+
 QT_END_NAMESPACE
 
 QT_END_HEADER
diff --git a/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp b/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp
index 78f007af80..76c0fc54de 100644
--- a/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp
+++ b/src/quick/scenegraph/coreapi/qsgnodeupdater.cpp
@@ -164,9 +164,6 @@ void QSGNodeUpdater::enterClipNode(QSGClipNode *c)
     qDebug() << "enter clip:" << c;
 #endif
 
-    if (c->dirtyState() & QSGNode::DirtyClipList)
-        ++m_force_update;
-
     c->m_matrix = m_combined_matrix_stack.isEmpty() ? 0 : m_combined_matrix_stack.last();
     c->m_clip_list = m_current_clip;
     m_current_clip = c;
@@ -179,9 +176,6 @@ void QSGNodeUpdater::leaveClipNode(QSGClipNode *c)
     qDebug() << "leave clip:" << c;
 #endif
 
-    if (c->dirtyState() & QSGNode::DirtyClipList)
-        --m_force_update;
-
     m_current_clip = c->m_clip_list;
 }
 
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);