Class documentation fixes for declarative.

5 files changed, 62 insertions, 18 deletions

diff --git a/src/declarative/qml/qdeclarativenetworkaccessmanagerfactory.cpp b/src/declarative/qml/qdeclarativenetworkaccessmanagerfactory.cpp
index 9dd7d39..f5f1a1f 100644
--- a/src/declarative/qml/qdeclarativenetworkaccessmanagerfactory.cpp
+++ b/src/declarative/qml/qdeclarativenetworkaccessmanagerfactory.cpp
@@ -56,12 +56,17 @@ QT_BEGIN_NAMESPACE
     To implement a factory, subclass QDeclarativeNetworkAccessManagerFactory and implement
     the create() method.
 
+    To use a factory, assign it to the relevant QDeclarativeEngine using
+    QDeclarativeEngine::setNetworkAccessManagerFactory().
+
     If the created QNetworkAccessManager becomes invalid, due to a
     change in proxy settings, for example, call the invalidate() method.
     This will cause all QNetworkAccessManagers to be recreated.
 
     Note: the create() method may be called by multiple threads, so ensure the
     implementation of this method is reentrant.
+
+    \sa QDeclarativeEngine::setNetworkAccessManagerFactory()
 */
 
 /*!
diff --git a/src/declarative/qml/qdeclarativeparserstatus.cpp b/src/declarative/qml/qdeclarativeparserstatus.cpp
index ec6260e..978bfb4 100644
--- a/src/declarative/qml/qdeclarativeparserstatus.cpp
+++ b/src/declarative/qml/qdeclarativeparserstatus.cpp
@@ -45,8 +45,36 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QDeclarativeParserStatus
-  \since 4.7
-    \brief The QDeclarativeParserStatus class provides updates on the parser state.
+    \since 4.7
+    \brief The QDeclarativeParserStatus class provides updates on the QML parser state.
+
+    QDeclarativeParserStatus provides a mechanism for classes instantiated by
+    a QDeclarativeEngine to receive notification at key points in their creation.
+
+    This class is often used for optimization purposes, as it allows you to defer an
+    expensive operation until after all the properties have been set on an
+    object. For example, QML's \l {Text} element uses the parser status
+    to defer text layout until all of its properties have been set (we
+    don't want to layout when the \c text is assigned, and then relayout
+    when the \c font is assigned, and relayout again when the \c width is assigned,
+    and so on).
+
+    To use QDeclarativeParserStatus, you must inherit both a QObject-derived class
+    and QDeclarativeParserStatus, and use the Q_INTERFACES() macro.
+
+    \code
+    class MyObject : public QObject, public QDeclarativeParserStatus
+    {
+        Q_OBJECT
+        Q_INTERFACES(QDeclarativeParserStatus)
+
+    public:
+        MyObject(QObject *parent = 0);
+        ...
+        void classBegin();
+        void componentComplete();
+    }
+    \endcode
 */
 
 /*! \internal */
diff --git a/src/declarative/qml/qdeclarativescriptstring.cpp b/src/declarative/qml/qdeclarativescriptstring.cpp
index 5b9afe9..8f717d1 100644
--- a/src/declarative/qml/qdeclarativescriptstring.cpp
+++ b/src/declarative/qml/qdeclarativescriptstring.cpp
@@ -55,24 +55,35 @@ public:
 
 /*!
 \class QDeclarativeScriptString
-  \since 4.7
+\since 4.7
 \brief The QDeclarativeScriptString class encapsulates a script and its context.
 
-The QDeclarativeScriptString is used by properties that want to accept a script "assignment" from QML.
+QDeclarativeScriptString is used to create QObject properties that accept a script "assignment" from QML.
 
-Normally, the following code would result in a binding being established for the \c script
-property.  If the property had a type of QDeclarativeScriptString, the script - \e {console.log(1921)} - itself
-would be passed to the property and it could choose how to handle it.
+Normally, the following QML would result in a binding being established for the \c script
+property; i.e. \c script would be assigned the value obtained from running \c {myObj.value = Math.max(myValue, 100)}
 
-\code
+\qml
 MyType {
-    script: console.log(1921)
+    script: myObj.value = Math.max(myValue, 100)
 }
+\endqml
+
+If instead the property had a type of QDeclarativeScriptString,
+the script itself -- \e {myObj.value = Math.max(myValue, 100)} -- would be passed to the \c script property
+and the class could choose how to handle it. Typically, the class will evaluate
+the script at some later time using a QDeclarativeExpression.
+
+\code
+QDeclarativeExpression expr(scriptString.context(), scriptString.script(), scriptStr.scopeObject());
+expr.value();
 \endcode
+
+\sa QDeclarativeExpression
 */
 
 /*!
-Construct an empty instance.
+Constructs an empty instance.
 */
 QDeclarativeScriptString::QDeclarativeScriptString()
 :  d(new QDeclarativeScriptStringPrivate)
@@ -80,7 +91,7 @@ QDeclarativeScriptString::QDeclarativeScriptString()
 }
 
 /*!
-Copy \a other.
+Copies \a other.
 */
 QDeclarativeScriptString::QDeclarativeScriptString(const QDeclarativeScriptString &other)
 : d(other.d)
@@ -95,7 +106,7 @@ QDeclarativeScriptString::~QDeclarativeScriptString()
 }
 
 /*!
-Assign \a other to this.
+Assigns \a other to this.
 */
 QDeclarativeScriptString &QDeclarativeScriptString::operator=(const QDeclarativeScriptString &other)
 {
@@ -104,7 +115,7 @@ QDeclarativeScriptString &QDeclarativeScriptString::operator=(const QDeclarative
 }
 
 /*!
-Return the context for the script.
+Returns the context for the script.
 */
 QDeclarativeContext *QDeclarativeScriptString::context() const
 {
diff --git a/src/declarative/util/qdeclarativepropertymap.cpp b/src/declarative/util/qdeclarativepropertymap.cpp
index 0e477b1..c8161a7 100644
--- a/src/declarative/util/qdeclarativepropertymap.cpp
+++ b/src/declarative/util/qdeclarativepropertymap.cpp
@@ -98,7 +98,7 @@ void QDeclarativePropertyMapMetaObject::propertyCreated(int, QMetaPropertyBuilde
 /*!
     \class QDeclarativePropertyMap
     \since 4.7
-    \brief The QDeclarativePropertyMap class allows you to set key-value pairs that can be used in bindings.
+    \brief The QDeclarativePropertyMap class allows you to set key-value pairs that can be used in QML bindings.
 
     QDeclarativePropertyMap provides a convenient way to expose domain data to the UI layer.
     The following example shows how you might declare data in C++ and then
@@ -112,7 +112,7 @@ void QDeclarativePropertyMapMetaObject::propertyCreated(int, QMetaPropertyBuilde
     ownerData.insert("phone", QVariant(QString("555-5555")));
 
     //expose it to the UI layer
-    QDeclarativeContext *ctxt = view->bindContext();
+    QDeclarativeContext *ctxt = view->rootContext();
     ctxt->setProperty("owner", &data);
     \endcode
 
diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp
index c0425ef..f786898 100644
--- a/src/declarative/util/qdeclarativeview.cpp
+++ b/src/declarative/util/qdeclarativeview.cpp
@@ -338,15 +338,15 @@ QDeclarativeContext* QDeclarativeView::rootContext()
     \value Null This QDeclarativeView has no source set.
     \value Ready This QDeclarativeView has loaded and created the QML component.
     \value Loading This QDeclarativeView is loading network data.
-    \value Error An error has occured.  Calling errorDescription() to retrieve a description.
+    \value Error An error has occured.  Call errorDescription() to retrieve a description.
 */
 
 /*! \enum QDeclarativeView::ResizeMode
 
   This enum specifies how to resize the view.
 
-  \value SizeViewToRootObject
-  \value SizeRootObjectToView
+  \value SizeViewToRootObject The view resizes with the root item in the QML.
+  \value SizeRootObjectToView The view will automatically resize the root item to the size of the view.
 */
 
 /*!