Doc: Fix documentation issues.

Change-Id: I03c4faa1aee60cd1ad706cb6c1b983f03311d251
Reviewed-by: aavit <qt_aavit@ovi.com>

7 files changed, 104 insertions, 27 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index d1fa60004e..12474fd53e 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -2952,7 +2952,8 @@ void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeo
     this item. Most implementations will return a single
     QSGGeometryNode containing the visual representation of this item.
     \a oldNode is the node that was returned the last time the
-    function was called.
+    function was called. \a updatePaintNodeData provides a pointer to
+    the QSGTransformNode associated with this QQuickItem.
 
     \code
     QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
@@ -2985,8 +2986,9 @@ void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeo
     QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty()
  */
 
-QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *)
+QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *updatePaintNodeData)
 {
+    Q_UNUSED(updatePaintNodeData)
     delete oldNode;
     return 0;
 }
diff --git a/src/quick/items/qquickpainteditem.cpp b/src/quick/items/qquickpainteditem.cpp
index 010842ef67..b20f0d5b5a 100644
--- a/src/quick/items/qquickpainteditem.cpp
+++ b/src/quick/items/qquickpainteditem.cpp
@@ -493,8 +493,7 @@ void QQuickPaintedItem::setRenderTarget(RenderTarget target)
 */
 
 /*!
-    This function is called when the Scene Graph node associated to the item needs to
-    be updated.
+    \reimp
 */
 QSGNode *QQuickPaintedItem::updatePaintNode(QSGNode *oldNode, UpdatePaintNodeData *data)
 {
diff --git a/src/quick/items/qquickview.cpp b/src/quick/items/qquickview.cpp
index 5027d813be..70fa69f333 100644
--- a/src/quick/items/qquickview.cpp
+++ b/src/quick/items/qquickview.cpp
@@ -185,7 +185,7 @@ QQuickView::QQuickView(const QUrl &source, QWindow *parent)
 
   Note: In this case, the QQuickView does not own the given \a engine object;
   it is the caller's responsibility to destroy the engine. If the \a engine is deleted
-  before the view \a status() will return \a QQuickView::Error.
+  before the view, status() will return QQuickView::Error.
 
   \sa Status, status(), errors()
 */
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index bef783599e..c761b38d23 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -141,6 +141,12 @@ private:
 
 
 #ifndef QT_NO_ACCESSIBILITY
+/*!
+    Returns an accessibility interface for this window, or 0 if such an
+    interface cannot be created.
+
+    \warning The caller is responsible for deleting the returned interface.
+*/
 QAccessibleInterface *QQuickWindow::accessibleRoot() const
 {
     return QAccessible::queryAccessibleInterface(const_cast<QQuickWindow*>(this));
@@ -400,6 +406,11 @@ void QQuickWindowPrivate::init(QQuickWindow *c)
     QObject::connect(context, SIGNAL(invalidated()), q, SLOT(cleanupSceneGraph()), Qt::DirectConnection);
 }
 
+/*!
+    \property QQuickWindow::data
+    \internal
+*/
+
 QQmlListProperty<QObject> QQuickWindowPrivate::data()
 {
     initRootItem();
@@ -910,6 +921,10 @@ void QQuickWindowPrivate::cleanup(QSGNode *n)
     \sa {OpenGL Under QML Example}
 
 */
+
+/*!
+    Constructs a window for displaying a QML scene with parent window \a parent.
+*/
 QQuickWindow::QQuickWindow(QWindow *parent)
     : QWindow(*(new QQuickWindowPrivate), parent)
 {
@@ -917,6 +932,9 @@ QQuickWindow::QQuickWindow(QWindow *parent)
     d->init(this);
 }
 
+/*!
+    \internal
+*/
 QQuickWindow::QQuickWindow(QQuickWindowPrivate &dd, QWindow *parent)
     : QWindow(dd, parent)
 {
@@ -924,6 +942,9 @@ QQuickWindow::QQuickWindow(QQuickWindowPrivate &dd, QWindow *parent)
     d->init(this);
 }
 
+/*!
+    Destroys the window.
+*/
 QQuickWindow::~QQuickWindow()
 {
     Q_D(QQuickWindow);
@@ -961,8 +982,8 @@ void QQuickWindow::releaseResources()
 
 
 /*!
-    Controls whether the OpenGL context can be released as a part of a call to
-    releaseResources().
+    Sets whether the OpenGL context can be released as a part of a call to
+    releaseResources() to \a persistent.
 
     The OpenGL context might still be released when the user makes an explicit
     call to hide().
@@ -991,8 +1012,8 @@ bool QQuickWindow::isPersistentOpenGLContext() const
 
 
 /*!
-    Controls whether the scene graph nodes and resources can be released as a
-    part of a call to releaseResources().
+    Sets whether the scene graph nodes and resources can be released as a
+    part of a call to releaseResources() to \a persistent.
 
     The scene graph nodes and resources might still be released when the user
     makes an explicit call to hide().
@@ -1024,7 +1045,8 @@ bool QQuickWindow::isPersistentSceneGraph() const
 
 
 /*!
-  Returns the invisible root item of the scene.
+    \property QQuickWindow::contentItem
+    \brief The invisible root item of the scene.
 
   A QQuickWindow always has a single invisible root item containing all of its content.
   To add items to this window, reparent the items to the contentItem or to an existing
@@ -1975,7 +1997,9 @@ bool QQuickWindowPrivate::dragOverThreshold(qreal d, Qt::Axis axis, QMouseEvent
 }
 
 /*!
-    Propagates an event to a QQuickItem on the window
+    Propagates an event \a e to a QQuickItem \a item on the window.
+
+    The return value is currently not used.
 */
 bool QQuickWindow::sendEvent(QQuickItem *item, QEvent *e)
 {
@@ -2393,6 +2417,14 @@ QOpenGLContext *QQuickWindow::openglContext() const
     return 0;
 }
 
+/*!
+    \fn void QQuickWindow::frameSwapped()
+
+    This signal is emitted when the frame buffers have been swapped.
+
+    This signal will be emitted from the scene graph rendering thread.
+*/
+
 
 /*!
     \fn void QQuickWindow::sceneGraphInitialized()
@@ -2448,7 +2480,18 @@ void QQuickWindow::setRenderTarget(QOpenGLFramebufferObject *fbo)
 
 /*!
     \overload
- */
+
+    Sets the render target for this window to be an FBO with
+    \a fboId and \a size.
+
+    The specified FBO must be created in the context of the window
+    or one that shares with it.
+
+    \warning
+    This function can only be called from the thread doing
+    the rendering.
+*/
+
 void QQuickWindow::setRenderTarget(uint fboId, const QSize &size)
 {
     Q_D(QQuickWindow);
@@ -2549,6 +2592,25 @@ QQmlIncubationController *QQuickWindow::incubationController() const
  */
 
 /*!
+    \fn void QQuickWindow::beforeSynchronizing()
+
+    This signal is emitted before the scene graph is synchronized with the QML state.
+
+    This signal can be used to do any preparation required before calls to
+    QQuickItem::updatePaintNode().
+
+    The GL context used for rendering the scene graph will be bound at this point.
+
+    \warning This signal is emitted from the scene graph rendering thread. If your
+    slot function needs to finish before execution continues, you must make sure that
+    the connection is direct (see Qt::ConnectionType).
+
+    \warning Make very sure that a signal handler for beforeSynchronizing leaves the GL
+    context in the same state as it was when the signal handler was entered. Failing to
+    do so can result in the scene not rendering properly.
+*/
+
+/*!
     \fn void QQuickWindow::beforeRendering()
 
     This signal is emitted before the scene starts rendering.
@@ -2559,8 +2621,9 @@ QQmlIncubationController *QQuickWindow::incubationController() const
     The GL context used for rendering the scene graph will be bound
     at this point.
 
-    \warning Since this signal is emitted from the scene graph rendering thread, the
-    receiver should be on the scene graph thread or the connection should be Qt::DirectConnection.
+    \warning This signal is emitted from the scene graph rendering thread. If your
+    slot function needs to finish before execution continues, you must make sure that
+    the connection is direct (see Qt::ConnectionType).
 
     \warning Make very sure that a signal handler for beforeRendering leaves the GL
     context in the same state as it was when the signal handler was entered. Failing to
@@ -2577,8 +2640,9 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 
     The GL context used for rendering the scene graph will be bound at this point.
 
-    \warning Since this signal is emitted from the scene graph rendering thread, the
-    receiver should be on the scene graph thread or the connection should be Qt::DirectConnection.
+    \warning This signal is emitted from the scene graph rendering thread. If your
+    slot function needs to finish before execution continues, you must make sure that
+    the connection is direct (see Qt::ConnectionType).
 
     \warning Make very sure that a signal handler for afterRendering() leaves the GL
     context in the same state as it was when the signal handler was entered. Failing to
@@ -2589,7 +2653,7 @@ QQmlIncubationController *QQuickWindow::incubationController() const
 
 /*!
     Sets weither the scene graph rendering of QML should clear the color buffer
-    before it starts rendering to \a enbled.
+    before it starts rendering to \a enabled.
 
     By disabling clearing of the color buffer, it is possible to do GL painting
     under the scene graph.
@@ -2657,7 +2721,7 @@ QSGTexture *QQuickWindow::createTextureFromImage(const QImage &image) const
 
 
 /*!
-    Creates a new QSGTexture object from an existing GL texture \a id.
+    Creates a new QSGTexture object from an existing GL texture \a id and \a size.
 
     The caller of the function is responsible for deleting the returned texture.
 
@@ -2683,11 +2747,12 @@ QSGTexture *QQuickWindow::createTextureFromId(uint id, const QSize &size, Create
     return 0;
 }
 
-
 /*!
-    Sets the color used to clear the opengl context to \a color.
+    \property QQuickWindow::color
+    \brief The color used to clear the OpenGL context.
 
     Setting the clear color has no effect when clearing is disabled.
+    By default, the clear color is white.
 
     \sa setClearBeforeRendering()
  */
@@ -2702,12 +2767,6 @@ void QQuickWindow::setColor(const QColor &color)
     emit colorChanged(color);
 }
 
-
-
-/*!
-    Returns the color used to clear the opengl context.
- */
-
 QColor QQuickWindow::color() const
 {
     return d_func()->clearColor;
diff --git a/src/quick/scenegraph/coreapi/qsgmaterial.cpp b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
index c67b98b875..50d445c28f 100644
--- a/src/quick/scenegraph/coreapi/qsgmaterial.cpp
+++ b/src/quick/scenegraph/coreapi/qsgmaterial.cpp
@@ -561,6 +561,9 @@ QSGMaterial::~QSGMaterial()
     \value RequiresDeterminant Set this flag to true if the material relies on
     the determinant of the matrix of the geometry nodes for rendering.
 
+    \value RequiresFullMatrixExceptTranslate Set this flag to true if the material
+    relies on the full matrix of the geometry nodes for rendering, except the translation part.
+
     \value RequiresFullMatrix Set this flag to true if the material relies on
     the full matrix of the geometry nodes for rendering.
  */
diff --git a/src/quick/scenegraph/util/qsgsimplerectnode.cpp b/src/quick/scenegraph/util/qsgsimplerectnode.cpp
index 09a3b42e98..d8a1ff914b 100644
--- a/src/quick/scenegraph/util/qsgsimplerectnode.cpp
+++ b/src/quick/scenegraph/util/qsgsimplerectnode.cpp
@@ -93,6 +93,13 @@ void QSGSimpleRectNode::setRect(const QRectF &rect)
 }
 
 
+/*!
+    \fn void QSGSimpleRectNode::setRect(qreal x, qreal y, qreal w, qreal h)
+    \overload
+
+    Sets the rectangle of this rect node to begin at (\a x, \a y) and have
+    width \a w and height \a h.
+ */
 
 /*!
     Returns the rectangle that this rect node covers.
diff --git a/src/quick/scenegraph/util/qsgsimpletexturenode.cpp b/src/quick/scenegraph/util/qsgsimpletexturenode.cpp
index c347dffbed..98f806652c 100644
--- a/src/quick/scenegraph/util/qsgsimpletexturenode.cpp
+++ b/src/quick/scenegraph/util/qsgsimpletexturenode.cpp
@@ -105,7 +105,7 @@ QSGTexture::Filtering QSGSimpleTextureNode::filtering() const
 
 
 /*!
-    Sets the target rect of this texture node to \a r
+    Sets the target rect of this texture node to \a r.
  */
 void QSGSimpleTextureNode::setRect(const QRectF &r)
 {
@@ -116,6 +116,13 @@ void QSGSimpleTextureNode::setRect(const QRectF &r)
     markDirty(DirtyGeometry);
 }
 
+/*!
+    \fn void QSGSimpleTextureNode::setRect(qreal x, qreal y, qreal w, qreal h)
+    \overload
+
+    Sets the rectangle of this texture node to begin at (\a x, \a y) and have
+    width \a w and height \a h.
+ */
 
 /*!
     Returns the target rect of this texture node.