Doc fixes, improvements

1 files changed, 44 insertions, 58 deletions

diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index a7384a9..8679e76 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -153,11 +153,11 @@ void QDeclarativeEnginePrivate::defineModule()
 
 /*!
 \qmlclass Qt QDeclarativeEnginePrivate
-\brief The QML Global Qt Object
+\brief The QML global Qt object provides useful enums and functions from Qt.
 
-The Qt object provides useful enums and functions from Qt, for use in all QML
-files. Note that you do note create instances of this type, but instead use
-the members of the global "Qt" object.
+The Qt object provides useful enums and functions from Qt, for use in all QML files. 
+
+You do not create instances of this type, but instead use the members of the global "Qt" object.
 
 \section1 Enums
 
@@ -172,23 +172,23 @@ data types. This is primarily useful when setting the properties of an item
 when the property has one of the following types:
 
 \list
-\o Color
-\o Rect
-\o Point
-\o Size
-\o Vector3D
+\o \c color - use \l{Qt::rgba()}{Qt.rgba()}, \l{Qt::darker()}{Qt.darker()}, \l{Qt::lighter()}{Qt.lighter()} or \l{Qt::tint()}{Qt.tint()}
+\o \c rect - use \l{Qt::rect()}{Qt.rect()}
+\o \c point - use \l{Qt::point()}{Qt.point()}
+\o \c size - use \l{Qt::size()}{Qt.size()}
+\o \c vector3d - use \l{Qt::vector3d()}{Qt.vector3d()}
 \endlist
 
-There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{Qml Types}.
+There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{QML Basic Types}.
 
 \section1 Date/Time Formatters
 
 The Qt object contains several functions for formatting dates and times.
 
 \list
-    \o \l{Qt::formatDateTime}{string Qt.formatDateTime(datetime date, variant format)
-    \o \l{Qt::formatDate}{string Qt.formatDate(datetime date, variant format)
-    \o \l{Qt::formatTime}{string Qt.formatTime(datetime date, variant format)
+    \o \l{Qt::formatDateTime}{string Qt.formatDateTime(datetime date, variant format)}
+    \o \l{Qt::formatDate}{string Qt.formatDate(datetime date, variant format)}
+    \o \l{Qt::formatTime}{string Qt.formatTime(datetime date, variant format)}
 \endlist
 
 The format specification is described at \l{Qt::formatDateTime}{Qt.formatDateTime}.
@@ -226,8 +226,7 @@ QDeclarativeEnginePrivate::QDeclarativeEnginePrivate(QDeclarativeEngine *e)
 
 /*!
 \qmlmethod url Qt::resolvedUrl(url)
-This function returns \c url resolved relative to the URL of the
-caller.
+Returns \c url resolved relative to the URL of the caller.
 */
 QUrl QDeclarativeScriptEngine::resolvedUrl(QScriptContext *context, const QUrl& url)
 {
@@ -1035,8 +1034,11 @@ QString QDeclarativeEnginePrivate::urlToLocalFileOrQrc(const QUrl& url)
 /*!
 \qmlmethod object Qt::createComponent(url)
 
-This function takes the URL of a QML file as its only argument. It returns
-a component object which can be used to create and load that QML file.
+Returns a \l Component object created from the QML file at the specified \a url,
+or \c null if there was an error in creating the component.
+
+Call \l {Component::createObject()}{Component.createObject()} on the returned
+component to create an object instance of the component.
 
 Here is an example. Remember that QML files that might be loaded
 over the network cannot be expected to be ready immediately.
@@ -1049,17 +1051,8 @@ If you are certain the files will be local, you could simplify to:
 
 \snippet doc/src/snippets/declarative/componentCreation.js 2
 
-The methods and properties of the \l {Component} element are defined in its own
-page, but when using it dynamically only two methods are usually used.
- \l {Component::createObject()}{Component.createObject()} returns the created object or \c null if there is an error.
-If there is an error, \l {Component::errorString()}{Component.errorString()} describes
-the error that occurred. Note that createObject() takes exactly one argument, which is set
-to the parent of the created object. Graphical objects without a parent will not appear
-on the scene, but if you do not wish to parent the item at this point you can safely pass
-in null.
-
-If you want to just create an arbitrary string of QML, instead of
-loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function.
+To create a QML object from an arbitrary string of QML (instead of a file),
+use \l{Qt::createQmlObject()}{Qt.createQmlObject()}.
 */
 
 QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1088,29 +1081,22 @@ QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QS
 /*!
 \qmlmethod object Qt::createQmlObject(string qml, object parent, string filepath)
 
-Creates a new object from the specified string of QML. It requires a
-second argument, which is the id of an existing QML object to use as
-the new object's parent. If a third argument is provided, this is used
-for error reporting as the filepath that the QML came from.
+Returns a new object created from the given \a string of QML with the specified \a parent,
+or \c null if there was an error in creating the object.
+
+If \a filepath is specified, it will be used for error reporting for the created object.
 
 Example (where \c targetItem is the id of an existing QML item):
 
 \snippet doc/src/snippets/declarative/createQmlObject.qml 0
 
-This function is intended for use inside QML only. It is intended to behave
-similarly to eval, but for creating QML elements.
-
-Returns the created object, \c or null if there is an error. In the case of an
-error, a QtScript Error object is thrown. This object has the additional property,
-qmlErrors, which is an array of all the errors encountered when trying to execute the
-QML. Each object in the array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
+In the case of an error, a QtScript Error object is thrown. This object has an additional property,
+\c qmlErrors, which is an array of the errors encountered.
+Each object in this array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
 
 Note that this function returns immediately, and therefore may not work if
-the QML loads new components. If you are trying to load a new component,
-for example from a QML file, consider the \l{Qt.createComponent(url file)}{Qt.createComponent()} function
-instead. 'New components' refers to external QML files that have not yet
-been loaded, and so it is safe to use \c Qt.createQmlObject() to load built-in
-components.
+the \a qml string loads new components (that is, external QML files that have not yet been loaded).
+If this is the case, consider using \l{Qt::createComponent()}{Qt.createComponent()} instead.
 */
 
 QScriptValue QDeclarativeEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1217,7 +1203,7 @@ QScriptValue QDeclarativeEnginePrivate::isQtObject(QScriptContext *ctxt, QScript
 
 /*!
 \qmlmethod Qt::vector3d(real x, real y, real z)
-This function returns a Vector3D with the specified \c x, \c y and \c z.
+Returns a Vector3D with the specified \c x, \c y and \c z.
 */
 QScriptValue QDeclarativeEnginePrivate::vector3d(QScriptContext *ctxt, QScriptEngine *engine)
 {
@@ -1231,7 +1217,7 @@ QScriptValue QDeclarativeEnginePrivate::vector3d(QScriptContext *ctxt, QScriptEn
 
 /*!
 \qmlmethod string Qt::formatDate(datetime date, variant format)
-This function returns the string representation of \c date, formatted according to \c format.
+Returns the string representation of \c date, formatted according to \c format.
 */
 QScriptValue QDeclarativeEnginePrivate::formatDate(QScriptContext*ctxt, QScriptEngine*engine)
 {
@@ -1256,7 +1242,7 @@ QScriptValue QDeclarativeEnginePrivate::formatDate(QScriptContext*ctxt, QScriptE
 
 /*!
 \qmlmethod string Qt::formatTime(datetime time, variant format)
-This function returns the string representation of \c time, formatted according to \c format.
+Returns the string representation of \c time, formatted according to \c format.
 
 See Qt::formatDateTime for how to define \c format.
 */
@@ -1283,7 +1269,7 @@ QScriptValue QDeclarativeEnginePrivate::formatTime(QScriptContext*ctxt, QScriptE
 
 /*!
 \qmlmethod string Qt::formatDateTime(datetime dateTime, variant format)
-This function returns the string representation of \c dateTime, formatted according to \c format.
+Returns the string representation of \c dateTime, formatted according to \c format.
 
 \c format for the date/time formatting functions is be specified as follows.
 
@@ -1374,7 +1360,7 @@ QScriptValue QDeclarativeEnginePrivate::formatDateTime(QScriptContext*ctxt, QScr
 /*!
 \qmlmethod color Qt::rgba(real red, real green, real blue, real alpha)
 
-This function returns a Color with the specified \c red, \c green, \c blue and \c alpha components.
+Returns a Color with the specified \c red, \c green, \c blue and \c alpha components.
 All components should be in the range 0-1 inclusive.
 */
 QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1402,7 +1388,7 @@ QScriptValue QDeclarativeEnginePrivate::rgba(QScriptContext *ctxt, QScriptEngine
 /*!
 \qmlmethod color Qt::hsla(real hue, real saturation, real lightness, real alpha)
 
-This function returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components.
+Returns a Color with the specified \c hue, \c saturation, \c lightness and \c alpha components.
 All components should be in the range 0-1 inclusive.
 */
 QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1430,7 +1416,7 @@ QScriptValue QDeclarativeEnginePrivate::hsla(QScriptContext *ctxt, QScriptEngine
 /*!
 \qmlmethod rect Qt::rect(int x, int y, int width, int height) 
 
-This function returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height.
+Returns a Rect with the top-left corner at \c x, \c y and the specified \c width and \c height.
 */
 QScriptValue QDeclarativeEnginePrivate::rect(QScriptContext *ctxt, QScriptEngine *engine)
 {
@@ -1450,7 +1436,7 @@ QScriptValue QDeclarativeEnginePrivate::rect(QScriptContext *ctxt, QScriptEngine
 
 /*!
 \qmlmethod point Qt::point(int x, int y)
-This function returns a Point with the specified \c x and \c y coordinates.
+Returns a Point with the specified \c x and \c y coordinates.
 */
 QScriptValue QDeclarativeEnginePrivate::point(QScriptContext *ctxt, QScriptEngine *engine)
 {
@@ -1463,7 +1449,7 @@ QScriptValue QDeclarativeEnginePrivate::point(QScriptContext *ctxt, QScriptEngin
 
 /*!
 \qmlmethod Qt::size(int width, int height)
-This function returns as Size with the specified \c width and \c height.
+Returns a Size with the specified \c width and \c height.
 */
 QScriptValue QDeclarativeEnginePrivate::size(QScriptContext *ctxt, QScriptEngine *engine)
 {
@@ -1476,7 +1462,7 @@ QScriptValue QDeclarativeEnginePrivate::size(QScriptContext *ctxt, QScriptEngine
 
 /*!
 \qmlmethod color Qt::lighter(color baseColor, real factor)
-This function returns a color lighter than \c baseColor by the \c factor provided.
+Returns a color lighter than \c baseColor by the \c factor provided.
 
 If the factor is greater than 1.0, this functions returns a lighter color.
 Setting factor to 1.5 returns a color that is 50% brighter. If the factor is less than 1.0,
@@ -1512,7 +1498,7 @@ QScriptValue QDeclarativeEnginePrivate::lighter(QScriptContext *ctxt, QScriptEng
 
 /*!
 \qmlmethod color Qt::darker(color baseColor, real factor)
-This function returns a color darker than \c baseColor by the \c factor provided.
+Returns a color darker than \c baseColor by the \c factor provided.
 
 If the factor is greater than 1.0, this function returns a darker color.
 Setting factor to 3.0 returns a color that has one-third the brightness.
@@ -1549,7 +1535,7 @@ QScriptValue QDeclarativeEnginePrivate::darker(QScriptContext *ctxt, QScriptEngi
 
 /*!
 \qmlmethod bool Qt::openUrlExternally(url target)
-This function attempts to open the specified \c target url in an external application, based on the user's desktop preferences. It will return true if it succeeds, and false otherwise.
+Attempts to open the specified \c target url in an external application, based on the user's desktop preferences. Returns true if it succeeds, and false otherwise.
 */
 QScriptValue QDeclarativeEnginePrivate::desktopOpenUrl(QScriptContext *ctxt, QScriptEngine *e)
 {
@@ -1564,7 +1550,7 @@ QScriptValue QDeclarativeEnginePrivate::desktopOpenUrl(QScriptContext *ctxt, QSc
 
 /*!
 \qmlmethod list<string> Qt::fontFamilies()
-This function returns a list of the font families available to the application.
+Returns a list of the font families available to the application.
 */
 
 QScriptValue QDeclarativeEnginePrivate::fontFamilies(QScriptContext *ctxt, QScriptEngine *e)
@@ -1579,7 +1565,7 @@ QScriptValue QDeclarativeEnginePrivate::fontFamilies(QScriptContext *ctxt, QScri
 
 /*!
 \qmlmethod string Qt::md5(data)
-This function returns a hex string of the md5 hash of \c data.
+Returns a hex string of the md5 hash of \c data.
 */
 QScriptValue QDeclarativeEnginePrivate::md5(QScriptContext *ctxt, QScriptEngine *)
 {