Doc fixes

7 files changed, 90 insertions, 55 deletions

diff --git a/doc/src/snippets/declarative/mouseregion.qml b/doc/src/snippets/declarative/mouseregion.qml
index a464069..683770b 100644
--- a/doc/src/snippets/declarative/mouseregion.qml
+++ b/doc/src/snippets/declarative/mouseregion.qml
@@ -3,13 +3,21 @@ import Qt 4.7
 Rectangle { width: 200; height: 100
 Row {
 //! [0]
-Rectangle { width: 100; height: 100; color: "green"
-    MouseArea { anchors.fill: parent; onClicked: { parent.color = 'red' } }
+Rectangle { 
+    width: 100; height: 100
+    color: "green"
+
+    MouseArea { 
+        anchors.fill: parent
+        onClicked: { parent.color = 'red' }
+    }
 }
 //! [0]
 //! [1]
 Rectangle {
-    width: 100; height: 100; color: "green"
+    width: 100; height: 100
+    color: "green"
+
     MouseArea {
         anchors.fill: parent
         acceptedButtons: Qt.LeftButton | Qt.RightButton
diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 247e348..1031493 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -54,7 +54,7 @@ QT_BEGIN_NAMESPACE
     \brief The Image element allows you to add bitmaps to a scene.
     \inherits Item
 
-    The Image element supports untransformed, stretched and tiled.
+    The Image element supports untransformed, stretched and tiled images.
 
     For an explanation of stretching and tiling, see the fillMode property description.
 
diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index 0328f91..fe656fa 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -155,8 +155,8 @@ void QDeclarativeGradient::doUpdate()
     \brief The Rectangle item allows you to add rectangles to a scene.
     \inherits Item
 
-    A Rectangle is painted having a solid fill (color) and an optional border.
-    You can also create rounded rectangles using the radius property.
+    A Rectangle is painted using a solid fill (color) and an optional border.
+    You can also create rounded rectangles using the \l radius property.
 
     \qml
     Rectangle {
@@ -223,14 +223,22 @@ QDeclarativePen *QDeclarativeRectangle::border()
     \o \image declarative-rect_gradient.png
     \o
     \qml
-    Rectangle { y: 0; width: 80; height: 80; color: "lightsteelblue" }
-    Rectangle { y: 100; width: 80; height: 80
+    Rectangle {
+        y: 0; width: 80; height: 80
+        color: "lightsteelblue"
+    }
+
+    Rectangle {
+        y: 100; width: 80; height: 80
         gradient: Gradient {
             GradientStop { position: 0.0; color: "lightsteelblue" }
             GradientStop { position: 1.0; color: "blue" }
         }
     }
-    Rectangle { rotation: 90; y: 200; width: 80; height: 80
+
+    Rectangle {
+        y: 200; width: 80; height: 80
+        rotation: 90
         gradient: Gradient {
             GradientStop { position: 0.0; color: "lightsteelblue" }
             GradientStop { position: 1.0; color: "blue" }
diff --git a/src/declarative/graphicsitems/qdeclarativerepeater.cpp b/src/declarative/graphicsitems/qdeclarativerepeater.cpp
index d49bb02..ca0b8c6 100644
--- a/src/declarative/graphicsitems/qdeclarativerepeater.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerepeater.cpp
@@ -67,7 +67,7 @@ QDeclarativeRepeaterPrivate::~QDeclarativeRepeaterPrivate()
 
     \brief The Repeater item allows you to repeat an Item-based component using a model.
 
-    The Repeater item is used when you want to create a large number of
+    The Repeater item is used to create a large number of
     similar items.  For each entry in the model, an item is instantiated
     in a context seeded with data from the model.  If the repeater will
     be instantiating a large number of instances, it may be more efficient to
diff --git a/src/declarative/graphicsitems/qdeclarativetext.cpp b/src/declarative/graphicsitems/qdeclarativetext.cpp
index 2b8da8e..37a63eb 100644
--- a/src/declarative/graphicsitems/qdeclarativetext.cpp
+++ b/src/declarative/graphicsitems/qdeclarativetext.cpp
@@ -116,7 +116,7 @@ QSet<QUrl> QTextDocumentWithImageResources::errors;
     \brief The Text item allows you to add formatted text to a scene.
     \inherits Item
 
-    It can display both plain and rich text. For example:
+    A Text item can display both plain and rich text. For example:
 
     \qml
     Text { text: "Hello World!"; font.family: "Helvetica"; font.pointSize: 24; color: "red" }
@@ -132,8 +132,8 @@ QSet<QUrl> QTextDocumentWithImageResources::errors;
     The \c elide property can alternatively be used to fit a single line of
     plain text to a set width.
 
-    Note that the \l{Supported HTML Subset} is limited, and that if IMG tags
-    load remote images, the text reloads (see resourcesLoading).
+    Note that the \l{Supported HTML Subset} is limited. Also, if the text contains
+    HTML img tags that load remote images, the text is reloaded.
 
     Text provides read-only text. For editable text, see \l TextEdit.
 */
@@ -191,7 +191,7 @@ QDeclarativeTextPrivate::~QDeclarativeTextPrivate()
 /*!
     \qmlproperty bool Text::font.bold
 
-    Sets the font's weight to bold.
+    Sets whether the font weight is bold.
 */
 
 /*!
@@ -216,25 +216,25 @@ QDeclarativeTextPrivate::~QDeclarativeTextPrivate()
 /*!
     \qmlproperty bool Text::font.italic
 
-    Sets the style of the text to italic.
+    Sets whether the font has an italic style.
 */
 
 /*!
     \qmlproperty bool Text::font.underline
 
-    Set the style of the text to underline.
+    Sets whether the text is underlined.
 */
 
 /*!
     \qmlproperty bool Text::font.outline
 
-    Set the style of the text to outline.
+    Sets whether the font has an outline style.
 */
 
 /*!
     \qmlproperty bool Text::font.strikeout
 
-    Set the style of the text to strikeout.
+    Sets whether the font has a strikeout style.
 */
 
 /*!
@@ -531,7 +531,14 @@ void QDeclarativeText::setWrapMode(WrapMode mode)
 
     The way the text property should be displayed.
 
-    Supported text formats are \c AutoText, \c PlainText, \c RichText and \c StyledText
+    Supported text formats are:
+    
+    \list
+    \o AutoText
+    \o PlainText
+    \o RichText
+    \o StyledText
+    \endlist
 
     The default is AutoText.  If the text format is AutoText the text element
     will automatically determine whether the text should be treated as
@@ -1069,8 +1076,9 @@ void QDeclarativeText::paint(QPainter *p, const QStyleOptionGraphicsItem *, QWid
 /*!
     \qmlproperty bool Text::smooth
 
-    Set this property if you want the text to be smoothly scaled or
-    transformed.  Smooth filtering gives better visual quality, but is slower.  If
+    This property holds whether the text is smoothly scaled or transformed.
+
+    Smooth filtering gives better visual quality, but is slower.  If
     the item is displayed at its natural size, this property has no visual or
     performance effect.
 
diff --git a/src/declarative/graphicsitems/qdeclarativetextedit.cpp b/src/declarative/graphicsitems/qdeclarativetextedit.cpp
index 25eaef6..31ed418 100644
--- a/src/declarative/graphicsitems/qdeclarativetextedit.cpp
+++ b/src/declarative/graphicsitems/qdeclarativetextedit.cpp
@@ -129,7 +129,7 @@ QString QDeclarativeTextEdit::text() const
 /*!
     \qmlproperty bool TextEdit::font.bold
 
-    Sets the font's weight to bold.
+    Sets whether the font weight is bold.
 */
 
 /*!
@@ -154,25 +154,25 @@ QString QDeclarativeTextEdit::text() const
 /*!
     \qmlproperty bool TextEdit::font.italic
 
-    Sets the style of the text to italic.
+    Sets whether the font has an italic style.
 */
 
 /*!
     \qmlproperty bool TextEdit::font.underline
 
-    Set the style of the text to underline.
+    Sets whether the text is underlined.
 */
 
 /*!
     \qmlproperty bool TextEdit::font.outline
 
-    Set the style of the text to outline.
+    Sets whether the font has an outline style.
 */
 
 /*!
     \qmlproperty bool TextEdit::font.strikeout
 
-    Set the style of the text to strikeout.
+    Sets whether the font has a strikeout style.
 */
 
 /*!
@@ -255,7 +255,12 @@ void QDeclarativeTextEdit::setText(const QString &text)
 
     The way the text property should be displayed.
 
-    Supported text formats are \c AutoText, \c PlainText and \c RichText.
+    \list
+    \o AutoText
+    \o PlainText
+    \o RichText
+    \o StyledText
+    \endlist
 
     The default is AutoText.  If the text format is AutoText the text edit
     will automatically determine whether the text should be treated as
@@ -991,8 +996,9 @@ void QDeclarativeTextEdit::updateImgCache(const QRectF &r)
 /*!
     \qmlproperty bool TextEdit::smooth
 
-    Set this property if you want the text to be smoothly scaled or
-    transformed.  Smooth filtering gives better visual quality, but is slower.  If
+    This property holds whether the text is smoothly scaled or transformed.
+
+    Smooth filtering gives better visual quality, but is slower.  If
     the item is displayed at its natural size, this property has no visual or
     performance effect.
 
diff --git a/src/declarative/graphicsitems/qdeclarativetextinput.cpp b/src/declarative/graphicsitems/qdeclarativetextinput.cpp
index b618183..43812b6 100644
--- a/src/declarative/graphicsitems/qdeclarativetextinput.cpp
+++ b/src/declarative/graphicsitems/qdeclarativetextinput.cpp
@@ -108,7 +108,7 @@ void QDeclarativeTextInput::setText(const QString &s)
 /*!
     \qmlproperty bool TextInput::font.bold
 
-    Sets the font's weight to bold.
+    Sets whether the font weight is bold.
 */
 
 /*!
@@ -133,25 +133,25 @@ void QDeclarativeTextInput::setText(const QString &s)
 /*!
     \qmlproperty bool TextInput::font.italic
 
-    Sets the style of the text to italic.
+    Sets whether the font has an italic style.
 */
 
 /*!
     \qmlproperty bool TextInput::font.underline
 
-    Set the style of the text to underline.
+    Sets whether the text is underlined.
 */
 
 /*!
     \qmlproperty bool TextInput::font.outline
 
-    Set the style of the text to outline.
+    Sets whether the font has an outline style.
 */
 
 /*!
     \qmlproperty bool TextInput::font.strikeout
 
-    Set the style of the text to strikeout.
+    Sets whether the font has a strikeout style.
 */
 
 /*!
@@ -827,7 +827,7 @@ void QDeclarativeTextInput::moveCursor()
     d->cursorItem->setX(d->control->cursorToX() - d->hscroll);
 }
 
-/*
+/*!
     \qmlmethod int xToPosition(int x)
 
     This function returns the character position at
@@ -1044,8 +1044,9 @@ void QDeclarativeTextInput::selectAll()
 /*!
     \qmlproperty bool TextInput::smooth
 
-    Set this property if you want the text to be smoothly scaled or
-    transformed.  Smooth filtering gives better visual quality, but is slower.  If
+    This property holds whether the text is smoothly scaled or transformed.
+
+    Smooth filtering gives better visual quality, but is slower.  If
     the item is displayed at its natural size, this property has no visual or
     performance effect.
 
@@ -1054,15 +1055,15 @@ void QDeclarativeTextInput::selectAll()
     filtering at the beginning of the animation and reenable it at the conclusion.
 */
 
-/*
+/*!
    \qmlproperty string TextInput::passwordCharacter
 
    This is the character displayed when echoMode is set to Password or
    PasswordEchoOnEdit. By default it is an asterisk.
 
-   Attempting to set this to more than one character will set it to
-   the first character in the string. Attempting to set this to less
-   than one character will fail.
+   If this property is set to a string with more than one character,
+   the first character is used. If the string is empty, the value
+   is ignored and the property is not set.
 */
 QString QDeclarativeTextInput::passwordCharacter() const
 {
@@ -1079,15 +1080,15 @@ void QDeclarativeTextInput::setPasswordCharacter(const QString &str)
     d->control->setPasswordCharacter(str.constData()[0]);
 }
 
-/*
+/*!
    \qmlproperty string TextInput::displayText
 
-   This is the actual text displayed in the TextInput. When
-   echoMode is set to TextInput::Normal this will be exactly
-   the same as the TextInput::text property. When echoMode
-   is set to something else, this property will contain the text
-   the user sees, while the text property will contain the
-   entered text.
+   This is the text displayed in the TextInput.
+   
+   If \l echoMode is set to TextInput::Normal, this holds the
+   same value as the TextInput::text property. Otherwise,
+   this property holds the text visible to the user, while
+   the \l text property holds the actual entered text.
 */
 QString QDeclarativeTextInput::displayText() const
 {
@@ -1095,26 +1096,30 @@ QString QDeclarativeTextInput::displayText() const
     return d->control->displayText();
 }
 
-/*
-    \qmlmethod void moveCursorSelection(int pos)
+/*!
+    \qmlmethod void moveCursorSelection(int position)
 
-    This method allows you to move the cursor while modifying the selection accordingly.
-    To simply move the cursor, set the cursorPosition property.
+    Moves the cursor to \a position and updates the selection accordingly.
+    (To only move the cursor, set the \l cursorPosition property.)
 
     When this method is called it additionally sets either the
     selectionStart or the selectionEnd (whichever was at the previous cursor position)
     to the specified position. This allows you to easily extend and contract the selected
     text range.
 
-    Example: The sequence of calls
+    For example, take this sequence of calls:
+
+    \code
         cursorPosition = 5
         moveCursorSelection(9)
         moveCursorSelection(7)
-    would move the cursor to position 5, extend the selection end from 5 to 9
+    \endcode
+
+    This moves the cursor to position 5, extend the selection end from 5 to 9
     and then retract the selection end from 9 to 7, leaving the text from position 5 to 7
     selected (the 6th and 7th characters).
 */
-void QDeclarativeTextInput::moveCursorSelection(int pos)
+void QDeclarativeTextInput::moveCursorSelection(int position)
 {
     Q_D(QDeclarativeTextInput);
     d->control->moveCursor(pos, true);