More class documentation fixes for declarative.

7 files changed, 77 insertions, 32 deletions

diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp
index 6657fea..5288923 100644
--- a/src/declarative/qml/qdeclarativecontext.cpp
+++ b/src/declarative/qml/qdeclarativecontext.cpp
@@ -114,7 +114,7 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
     \endcode
 
     All properties added explicitly by QDeclarativeContext::setContextProperty() take 
-    precedence over context object's properties.
+    precedence over the context object's properties.
 
     Contexts form a hierarchy.  The root of this heirarchy is the QDeclarativeEngine's
     \l {QDeclarativeEngine::rootContext()}{root context}.  A component instance can 
@@ -140,6 +140,11 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
     While QML objects instantiated in a context are not strictly owned by that 
     context, their bindings are.  If a context is destroyed, the property bindings of 
     outstanding QML objects will stop evaluating.
+
+    \note Setting the context object or adding new context properties after an object
+    has been created in that context is an expensive operation (essentially forcing all bindings
+    to reevaluate). Thus whenever possible you should complete "setup" of the context
+    before using it to create any objects.
 */
 
 /*! \internal */
diff --git a/src/declarative/qml/qdeclarativeerror.cpp b/src/declarative/qml/qdeclarativeerror.cpp
index 7e8aac0..17e91e3 100644
--- a/src/declarative/qml/qdeclarativeerror.cpp
+++ b/src/declarative/qml/qdeclarativeerror.cpp
@@ -49,8 +49,27 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QDeclarativeError
-  \since 4.7
-    \brief The QDeclarativeError class encapsulates a QML error
+    \since 4.7
+    \brief The QDeclarativeError class encapsulates a QML error.
+
+    QDeclarativeError includes a textual description of the error, as well
+    as location information (the file, line, and column). The toString()
+    method creates a single-line, human-readable string containing all of
+    this information, for example:
+    \code
+    file:///home/user/test.qml:7:8: Invalid property assignment: double expected
+    \endcode
+
+    You can use qDebug() or qWarning() to output errors to the console. This method
+    will attempt to open the file indicated by the error
+    and include additional contextual information.
+    \code
+    file:///home/user/test.qml:7:8: Invalid property assignment: double expected
+            y: "hello"
+               ^
+    \endcode
+
+    \sa QDeclarativeView::errors(), QDeclarativeComponent::errors()
 */
 class QDeclarativeErrorPrivate
 {
@@ -69,7 +88,7 @@ QDeclarativeErrorPrivate::QDeclarativeErrorPrivate()
 }
 
 /*!
-    Create an empty error object.
+    Creates an empty error object.
 */
 QDeclarativeError::QDeclarativeError()
 : d(0)
@@ -77,7 +96,7 @@ QDeclarativeError::QDeclarativeError()
 }
 
 /*!
-    Create a copy of \a other.
+    Creates a copy of \a other.
 */
 QDeclarativeError::QDeclarativeError(const QDeclarativeError &other)
 : d(0)
@@ -86,7 +105,7 @@ QDeclarativeError::QDeclarativeError(const QDeclarativeError &other)
 }
 
 /*!
-    Assign \a other to this error object.
+    Assigns \a other to this error object.
 */
 QDeclarativeError &QDeclarativeError::operator=(const QDeclarativeError &other)
 {
@@ -112,7 +131,7 @@ QDeclarativeError::~QDeclarativeError()
 }
 
 /*!
-    Return true if this error is valid, otherwise false.
+    Returns true if this error is valid, otherwise false.
 */
 bool QDeclarativeError::isValid() const
 {
@@ -120,7 +139,7 @@ bool QDeclarativeError::isValid() const
 }
 
 /*!
-    Return the url for the file that caused this error.
+    Returns the url for the file that caused this error.
 */
 QUrl QDeclarativeError::url() const
 {
@@ -129,7 +148,7 @@ QUrl QDeclarativeError::url() const
 }
 
 /*!
-    Set the \a url for the file that caused this error.
+    Sets the \a url for the file that caused this error.
 */
 void QDeclarativeError::setUrl(const QUrl &url)
 {
@@ -138,7 +157,7 @@ void QDeclarativeError::setUrl(const QUrl &url)
 }
 
 /*!
-    Return the error description.
+    Returns the error description.
 */
 QString QDeclarativeError::description() const
 {
@@ -147,7 +166,7 @@ QString QDeclarativeError::description() const
 }
 
 /*!
-    Set the error \a description.
+    Sets the error \a description.
 */
 void QDeclarativeError::setDescription(const QString &description)
 {
@@ -156,7 +175,7 @@ void QDeclarativeError::setDescription(const QString &description)
 }
 
 /*!
-    Return the error line number.
+    Returns the error line number.
 */
 int QDeclarativeError::line() const
 {
@@ -165,7 +184,7 @@ int QDeclarativeError::line() const
 }
 
 /*!
-    Set the error \a line number.
+    Sets the error \a line number.
 */
 void QDeclarativeError::setLine(int line)
 {
@@ -174,7 +193,7 @@ void QDeclarativeError::setLine(int line)
 }
 
 /*!
-    Return the error column number.
+    Returns the error column number.
 */
 int QDeclarativeError::column() const
 {
@@ -183,7 +202,7 @@ int QDeclarativeError::column() const
 }
 
 /*!
-    Set the error \a column number.
+    Sets the error \a column number.
 */
 void QDeclarativeError::setColumn(int column)
 {
@@ -192,7 +211,7 @@ void QDeclarativeError::setColumn(int column)
 }
 
 /*!
-    Return the error as a human readable string.
+    Returns the error as a human readable string.
 */
 QString QDeclarativeError::toString() const
 {
@@ -210,7 +229,7 @@ QString QDeclarativeError::toString() const
     \relates QDeclarativeError
     \fn QDebug operator<<(QDebug debug, const QDeclarativeError &error)
 
-    Output a human readable version of \a error to \a debug.
+    Outputs a human readable version of \a error to \a debug.
 */
 
 QDebug operator<<(QDebug debug, const QDeclarativeError &error)
diff --git a/src/declarative/qml/qdeclarativeextensionplugin.cpp b/src/declarative/qml/qdeclarativeextensionplugin.cpp
index 762c642d..863bfc4 100644
--- a/src/declarative/qml/qdeclarativeextensionplugin.cpp
+++ b/src/declarative/qml/qdeclarativeextensionplugin.cpp
@@ -59,6 +59,11 @@ QT_BEGIN_NAMESPACE
     function, and exporting the class using the Q_EXPORT_PLUGIN2()
     macro.
 
+    QML extension plugins can be used to provide either application-specific or
+    library-like plugins. Library plugins should limit themselves to registering types,
+    as any manipulation of the engine's root context may cause conflicts
+    or other issues in the library user's code.
+
     See \l {Extending QML in C++} for details how to write a QML extension plugin.
     See \l {How to Create Qt Plugins} for general Qt plugin documentation.
 
@@ -85,7 +90,7 @@ QDeclarativeExtensionPlugin::QDeclarativeExtensionPlugin(QObject *parent)
 }
 
 /*!
-  Destructor.
+  Destroys the plugin.
  */
 QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin()
 {
@@ -94,7 +99,9 @@ QDeclarativeExtensionPlugin::~QDeclarativeExtensionPlugin()
 /*!
     \fn void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri)
 
-    Initializes the extension from the \a uri using the \a engine.
+    Initializes the extension from the \a uri using the \a engine. Here an application
+    plugin might, for example, expose some data or objects to QML,
+    as context properties on the engine's root context.
 */
 
 void QDeclarativeExtensionPlugin::initializeEngine(QDeclarativeEngine *engine, const char *uri)
diff --git a/src/declarative/qml/qdeclarativeimageprovider.cpp b/src/declarative/qml/qdeclarativeimageprovider.cpp
index b992b9f..4be3472 100644
--- a/src/declarative/qml/qdeclarativeimageprovider.cpp
+++ b/src/declarative/qml/qdeclarativeimageprovider.cpp
@@ -45,31 +45,39 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \class QDeclarativeImageProvider
-    \brief The QDeclarativeImageProvider class provides an interface for threaded image requests.
+    \since 4.7
+    \brief The QDeclarativeImageProvider class provides an interface for threaded image requests in QML.
 
-    Note: the request() method may be called by multiple threads, so ensure the
+    QDeclarativeImageProvider can be used by a QDeclarativeEngine to provide images to QML asynchronously.
+    The image request will be run in a low priority thread, allowing potentially costly image
+    loading to be done in the background, without affecting the performance of the UI.
+
+    See the QDeclarativeEngine::addImageProvider() documentation for an
+    example of how a custom QDeclarativeImageProvider can be constructed and used.
+
+    \note the request() method may be called by multiple threads, so ensure the
     implementation of this method is reentrant.
 
     \sa QDeclarativeEngine::addImageProvider()
 */
 
 /*!
-  The destructor is virtual.
+  Destroys the image provider.
  */
 QDeclarativeImageProvider::~QDeclarativeImageProvider()
 {
 }
 
 /*!
-    \fn QImage QDeclarativeImageProvider::request(const QString &id, QSize *size, const QSize& requested_size)
+    \fn QImage QDeclarativeImageProvider::request(const QString &id, QSize *size, const QSize& requestedSize)
 
     Implement this method to return the image with \a id.
 
-    If \a requested_size is a valid size, resize the image to that size before returning.
+    If \a requestedSize is a valid size, the image returned should be of that size.
 
-    In any case, \a size must be set to the (original) size of the image.
+    In all cases, \a size must be set to the original size of the image.
 
-    Note: this method may be called by multiple threads, so ensure the
+    \note this method may be called by multiple threads, so ensure the
     implementation of this method is reentrant.
 */
 
diff --git a/src/declarative/qml/qdeclarativeimageprovider.h b/src/declarative/qml/qdeclarativeimageprovider.h
index 50b73fe..cc9c9af 100644
--- a/src/declarative/qml/qdeclarativeimageprovider.h
+++ b/src/declarative/qml/qdeclarativeimageprovider.h
@@ -54,7 +54,7 @@ class Q_DECLARATIVE_EXPORT QDeclarativeImageProvider
 {
 public:
     virtual ~QDeclarativeImageProvider();
-    virtual QImage request(const QString &id, QSize *size, const QSize& requested_size) = 0;
+    virtual QImage request(const QString &id, QSize *size, const QSize& requestedSize) = 0;
 };
 
 QT_END_NAMESPACE
diff --git a/src/declarative/qml/qdeclarativelist.cpp b/src/declarative/qml/qdeclarativelist.cpp
index 45b8cd7..31ef4c2 100644
--- a/src/declarative/qml/qdeclarativelist.cpp
+++ b/src/declarative/qml/qdeclarativelist.cpp
@@ -87,9 +87,10 @@ void QDeclarativeListReferencePrivate::release()
 
 /*!
 \class QDeclarativeListReference
+\since 4.7
 \brief The QDeclarativeListReference class allows the manipulation of QDeclarativeListProperty properties.
 
-QDeclarativeListReference allows programs to read from, and assign values to a QML list property in a 
+QDeclarativeListReference allows C++ programs to read from, and assign values to a QML list property in a
 simple and type safe way.  A QDeclarativeListReference can be created by passing an object and property
 name or through a QDeclarativeProperty instance.  These two are equivalant:
 
@@ -304,6 +305,7 @@ int QDeclarativeListReference::count() const
 
 /*!
 \class QDeclarativeListProperty
+\since 4.7
 \brief The QDeclarativeListProperty class allows applications to explose list-like 
 properties to QML.
 
@@ -313,10 +315,10 @@ The use of a list property from QML looks like this:
 \code
 FruitBasket {
     fruit: [ 
-             Apple {},
-             Orange{},
-             Banana {}
-           ]
+        Apple {},
+        Orange{},
+        Banana{}
+    ]
 }
 \endcode
 
@@ -336,6 +338,9 @@ Q_PROPERTY(QDeclarativeListProperty<Fruit> fruit READ fruit);
 
 QML list properties are typesafe - in this case \c {Fruit} is a QObject type that 
 \c {Apple}, \c {Orange} and \c {Banana} all derive from.
+
+\note QDeclarativeListProperty can only be used for lists of QObject-derived object pointers.
+
 */
 
 /*!
diff --git a/src/declarative/qml/qdeclarativeproperty.cpp b/src/declarative/qml/qdeclarativeproperty.cpp
index afd0d84..3881d0a 100644
--- a/src/declarative/qml/qdeclarativeproperty.cpp
+++ b/src/declarative/qml/qdeclarativeproperty.cpp
@@ -64,6 +64,7 @@ QT_BEGIN_NAMESPACE
 
 /*!
 \class QDeclarativeProperty
+\since 4.7
 \brief The QDeclarativeProperty class abstracts accessing properties on objects created from  QML.
 
 As QML uses Qt's meta-type system all of the existing QMetaObject classes can be used to introspect