From 1a7d04376d2b7ecbae69d14fb0d124e47507961d Mon Sep 17 00:00:00 2001
From: David Boddie <david.boddie@nokia.com>
Date: Wed, 9 Feb 2011 18:03:01 +0100
Subject: Doc: Snippet quoting and other documentation fixes.

---
 doc/src/declarative/qdeclarativemodels.qdoc        |  69 ++--------
 .../examples/activeqt/hierarchy-demo-snippet.qdoc  |  39 ++++++
 doc/src/examples/activeqt/hierarchy-demo.qdocinc   |   2 -
 doc/src/examples/activeqt/hierarchy.qdoc           |   2 +-
 doc/src/snippets/code/doc_src_qdbusadaptors.cpp    | 152 ++++++++++-----------
 .../declarative/models/views-models-delegates.qml  |  78 +++++++++++
 .../declarative/models/visual-model-and-view.qml   |  57 ++++++++
 doc/src/snippets/qtscript/evaluation/main.cpp      |   4 +-
 .../snippets/qtscript/registeringobjects/main.cpp  |   4 +-
 .../snippets/qtscript/registeringvalues/main.cpp   |   4 +-
 10 files changed, 267 insertions(+), 144 deletions(-)
 create mode 100644 doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc
 create mode 100644 doc/src/snippets/declarative/models/views-models-delegates.qml
 create mode 100644 doc/src/snippets/declarative/models/visual-model-and-view.qml

diff --git a/doc/src/declarative/qdeclarativemodels.qdoc b/doc/src/declarative/qdeclarativemodels.qdoc
index 9409eaf..5809659 100644
--- a/doc/src/declarative/qdeclarativemodels.qdoc
+++ b/doc/src/declarative/qdeclarativemodels.qdoc
@@ -108,7 +108,7 @@ XmlListModel allows construction of a model from an XML data source. The roles
 are specified via the \l XmlRole element.
 
 The following model has three roles, \e title, \e link and \e description:
-\code
+\qml
 XmlListModel {
      id: feedModel
      source: "http://rss.news.yahoo.com/rss/oceania"
@@ -117,7 +117,7 @@ XmlListModel {
      XmlRole { name: "link"; query: "link/string()" }
      XmlRole { name: "description"; query: "description/string()" }
 }
-\endcode
+\endqml
 
 The \l{demos/declarative/rssnews}{RSS News demo} shows how XmlListModel can
 be used to display an RSS feed.
@@ -131,19 +131,7 @@ This model contains both the data and delegate; the child items of a
 VisualItemModel provide the contents of the delegate. The model 
 does not provide any roles.
 
-\code
- VisualItemModel {
-     id: itemModel
-     Rectangle { height: 30; width: 80; color: "red" }
-     Rectangle { height: 30; width: 80; color: "green" }
-     Rectangle { height: 30; width: 80; color: "blue" }
- }
-
- ListView {
-     anchors.fill: parent
-     model: itemModel
- }
-\endcode
+\snippet doc/src/snippets/declarative/models/visual-model-and-view.qml visual model and view
 
 Note that in the above example there is no delegate required.
 The items of the model itself provide the visual elements that
@@ -339,7 +327,7 @@ An integer can be used to specify a model that contains a certain number
 of elements. In this case, the model does not have any data roles.
 
 The following example creates a ListView with five elements:
-\code
+\qml
 Item {
     width: 200; height: 250
 
@@ -355,7 +343,7 @@ Item {
     }
 
 }
-\endcode
+\endqml
 
 
 \section2 An Object Instance
@@ -367,7 +355,7 @@ The example below creates a list with one item, showing the color of the
 \e myText text.  Note the use of the fully qualified \e model.color property
 to avoid clashing with \e color property of the Text element in the delegate.
 
-\code
+\qml
 Rectangle {
     width: 200; height: 250
 
@@ -389,7 +377,7 @@ Rectangle {
         delegate: myDelegate
     }
 }
-\endcode
+\endqml
 
 \section1 Accessing Views and Models from Delegates
 
@@ -408,44 +396,7 @@ In the following example, the delegate shows the property \e{language}
 of the model, and the color of one of the fields depends on the
 property \e{fruit_color} of the view.
 
-\code
-Rectangle {
-     width: 200; height: 200
-
-    ListModel {
-        id: fruitModel
-        property string language: "en"
-        ListElement {
-            name: "Apple"
-            cost: 2.45
-        }
-        ListElement {
-            name: "Orange"
-            cost: 3.25
-        }
-        ListElement {
-            name: "Banana"
-            cost: 1.95
-        }
-    }
-
-    Component {
-        id: fruitDelegate
-        Row {
-                Text { text: " Fruit: " + name; color: ListView.view.fruit_color }
-                Text { text: " Cost: $" + cost }
-                Text { text: " Language: " + ListView.view.model.language }
-        }
-    }
-
-    ListView {
-        property color fruit_color: "green"
-        model: fruitModel
-        delegate: fruitDelegate
-        anchors.fill: parent
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/models/views-models-delegates.qml rectangle
 
 Another important case is when some action (e.g. mouse click) in the
 delegate should update data in the model. In this case you can define
@@ -457,9 +408,9 @@ a function in the model, e.g.:
 
 ...and call it from the delegate using:
 
-\code
+\js
         ListView.view.model.setData(index, field, value)
-\endcode
+\endjs
 
 ...assuming that \e{field} holds the name of the field which should be
 updated, and that \e{value} holds the new value.
diff --git a/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc b/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc
new file mode 100644
index 0000000..5df3224
--- /dev/null
+++ b/doc/src/examples/activeqt/hierarchy-demo-snippet.qdoc
@@ -0,0 +1,39 @@
+<script language="javascript">
+function createSubWidget( form )
+{
+    ParentWidget.createSubWidget( form.nameEdit.value );
+}
+
+function renameSubWidget( form )
+{
+    var SubWidget = ParentWidget.subWidget( form.nameEdit.value );
+    if ( !SubWidget ) {
+        alert( "No such widget " + form.nameEdit.value + "!" );
+        return;
+    }
+    SubWidget.label = form.labelEdit.value;
+    form.nameEdit.value = SubWidget.label;
+}
+
+function setFont( form )
+{
+    ParentWidget.font = form.fontEdit.value;
+}
+</script>
+
+<p>
+This widget can have many children!
+</p>
+<object ID="ParentWidget" CLASSID="CLSID:d574a747-8016-46db-a07c-b2b4854ee75c"
+CODEBASE="http://qt.nokia.com/demos/hierarchy.cab">
+[Object not available! Did you forget to build and register the server?]
+</object><br />
+<form>
+<input type="edit" ID="nameEdit" value="&lt;enter object name&gt;" />
+<input type="button" value="Create" onClick="createSubWidget(this.form)" />
+<input type="edit" ID="labelEdit" />
+<input type="button" value="Rename" onClick="renameSubWidget(this.form)" />
+<br />
+<input type="edit" ID="fontEdit" value="MS Sans Serif" />
+<input type="button" value = "Set Font" onClick="setFont(this.form)" />
+</form>
diff --git a/doc/src/examples/activeqt/hierarchy-demo.qdocinc b/doc/src/examples/activeqt/hierarchy-demo.qdocinc
index e7cb56e..86bfd87 100644
--- a/doc/src/examples/activeqt/hierarchy-demo.qdocinc
+++ b/doc/src/examples/activeqt/hierarchy-demo.qdocinc
@@ -1,5 +1,4 @@
 \raw HTML
-//! [0]
 <script language="javascript">
 function createSubWidget( form )
 {
@@ -39,5 +38,4 @@ CODEBASE="http://qt.nokia.com/demos/hierarchy.cab">
 <input type="edit" ID="fontEdit" value="MS Sans Serif" />
 <input type="button" value = "Set Font" onClick="setFont(this.form)" />
 </form>
-//! [0]
 \endraw
diff --git a/doc/src/examples/activeqt/hierarchy.qdoc b/doc/src/examples/activeqt/hierarchy.qdoc
index eb6cc71..8d14b68 100644
--- a/doc/src/examples/activeqt/hierarchy.qdoc
+++ b/doc/src/examples/activeqt/hierarchy.qdoc
@@ -84,5 +84,5 @@
     your WebBrowser to support ActiveX controls, and scripting to be
     enabled.
 
-    \snippet examples/activeqt/hierarchy-demo.qdocinc 0
+    \quotefile examples/activeqt/hierarchy-demo-snippet.qdoc
 */
diff --git a/doc/src/snippets/code/doc_src_qdbusadaptors.cpp b/doc/src/snippets/code/doc_src_qdbusadaptors.cpp
index abb31a1..749e64b 100644
--- a/doc/src/snippets/code/doc_src_qdbusadaptors.cpp
+++ b/doc/src/snippets/code/doc_src_qdbusadaptors.cpp
@@ -39,82 +39,82 @@
 ****************************************************************************/
 
 //! [0]
-        class MainApplicationAdaptor: public QDBusAbstractAdaptor
-        {
-            Q_OBJECT
-            Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
-            Q_PROPERTY(QString caption READ caption WRITE setCaption)
-            Q_PROPERTY(QString organizationName READ organizationName)
-            Q_PROPERTY(QString organizationDomain READ organizationDomain)
-
-        private:
-            QApplication *app;
-
-        public:
-            MainApplicationAdaptor(QApplication *application)
-                : QDBusAbstractAdaptor(application), app(application)
-            {
-                connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit()));
-                connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
-                        SLOT(focusChangedSlot(QWidget*, QWidget*)));
-            }
-
-            QString caption()
-            {
-                if (app->hasMainWindow())
-                    return app->mainWindow()->caption();
-                return QString(""); // must not return a null QString
-            }
-
-            void setCaption(const QString &newCaption)
-            {
-                if (app->hasMainWindow())
-                    app->mainWindow()->setCaption(newCaption);
-            }
-
-            QString organizationName()
-            {
-                return app->organizationName();
-            }
-
-            QString organizationDomain()
-            {
-                return app->organizationDomain();
-            }
-
-        public slots:
-            Q_NOREPLY void quit()
-            { app->quit(); }
-
-            void reparseConfiguration()
-            { app->reparseConfiguration(); }
-
-            QString mainWindowObject()
-            {
-                if (app->hasMainWindow())
-                    return QString("/%1/mainwindow").arg(app->applicationName());
-                return QString();
-            }
-
-            void setSessionManagement(bool enable)
-            {
-                if (enable)
-                   app->enableSessionManagement();
-                else
-                   app->disableSessionManagement();
-            }
-
-        private slots:
-            void focusChangedSlot(QWidget *, QWidget *now)
-            {
-                if (now == app->mainWindow())
-                    emit mainWindowHasFocus();
-            }
-
-        signals:
-            void aboutToQuit();
-            void mainWindowHasFocus();
-        };
+class MainApplicationAdaptor: public QDBusAbstractAdaptor
+{
+    Q_OBJECT
+    Q_CLASSINFO("D-Bus Interface", "org.kde.DBus.MainApplication")
+    Q_PROPERTY(QString caption READ caption WRITE setCaption)
+    Q_PROPERTY(QString organizationName READ organizationName)
+    Q_PROPERTY(QString organizationDomain READ organizationDomain)
+
+private:
+    QApplication *app;
+
+public:
+    MainApplicationAdaptor(QApplication *application)
+        : QDBusAbstractAdaptor(application), app(application)
+    {
+        connect(application, SIGNAL(aboutToQuit()), SIGNAL(aboutToQuit()));
+        connect(application, SIGNAL(focusChanged(QWidget*, QWidget*)),
+                SLOT(focusChangedSlot(QWidget*, QWidget*)));
+    }
+
+    QString caption()
+    {
+        if (app->hasMainWindow())
+            return app->mainWindow()->caption();
+        return QString(""); // must not return a null QString
+    }
+
+    void setCaption(const QString &newCaption)
+    {
+        if (app->hasMainWindow())
+            app->mainWindow()->setCaption(newCaption);
+    }
+
+    QString organizationName()
+    {
+        return app->organizationName();
+    }
+
+    QString organizationDomain()
+    {
+        return app->organizationDomain();
+    }
+
+public slots:
+    Q_NOREPLY void quit()
+    { app->quit(); }
+
+    void reparseConfiguration()
+    { app->reparseConfiguration(); }
+
+    QString mainWindowObject()
+    {
+        if (app->hasMainWindow())
+            return QString("/%1/mainwindow").arg(app->applicationName());
+        return QString();
+    }
+
+    void setSessionManagement(bool enable)
+    {
+        if (enable)
+           app->enableSessionManagement();
+        else
+           app->disableSessionManagement();
+    }
+
+private slots:
+    void focusChangedSlot(QWidget *, QWidget *now)
+    {
+        if (now == app->mainWindow())
+            emit mainWindowHasFocus();
+    }
+
+signals:
+    void aboutToQuit();
+    void mainWindowHasFocus();
+};
 //! [0]
 
 
diff --git a/doc/src/snippets/declarative/models/views-models-delegates.qml b/doc/src/snippets/declarative/models/views-models-delegates.qml
new file mode 100644
index 0000000..2f76856
--- /dev/null
+++ b/doc/src/snippets/declarative/models/views-models-delegates.qml
@@ -0,0 +1,78 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [rectangle]
+Rectangle {
+     width: 200; height: 200
+
+    ListModel {
+        id: fruitModel
+        property string language: "en"
+        ListElement {
+            name: "Apple"
+            cost: 2.45
+        }
+        ListElement {
+            name: "Orange"
+            cost: 3.25
+        }
+        ListElement {
+            name: "Banana"
+            cost: 1.95
+        }
+    }
+
+    Component {
+        id: fruitDelegate
+        Row {
+                Text { text: " Fruit: " + name; color: ListView.view.fruit_color }
+                Text { text: " Cost: $" + cost }
+                Text { text: " Language: " + ListView.view.model.language }
+        }
+    }
+
+    ListView {
+        property color fruit_color: "green"
+        model: fruitModel
+        delegate: fruitDelegate
+        anchors.fill: parent
+    }
+}
+//! [rectangle]
diff --git a/doc/src/snippets/declarative/models/visual-model-and-view.qml b/doc/src/snippets/declarative/models/visual-model-and-view.qml
new file mode 100644
index 0000000..4d42b65
--- /dev/null
+++ b/doc/src/snippets/declarative/models/visual-model-and-view.qml
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
+**     the names of its contributors may be used to endorse or promote
+**     products derived from this software without specific prior written
+**     permission.
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+Rectangle {
+    width: 200; height: 200
+
+    //! [visual model and view]
+    VisualItemModel {
+        id: itemModel
+        Rectangle { height: 30; width: 80; color: "red" }
+        Rectangle { height: 30; width: 80; color: "green" }
+        Rectangle { height: 30; width: 80; color: "blue" }
+    }
+
+    ListView {
+        anchors.fill: parent
+        model: itemModel
+    }
+    //! [visual model and view]
+}
diff --git a/doc/src/snippets/qtscript/evaluation/main.cpp b/doc/src/snippets/qtscript/evaluation/main.cpp
index e7efd8e..01e06b6 100644
--- a/doc/src/snippets/qtscript/evaluation/main.cpp
+++ b/doc/src/snippets/qtscript/evaluation/main.cpp
@@ -42,9 +42,9 @@
 
 int main(int argc, char *argv[])
 {
-//! [0]
+    //! [0]
     QScriptEngine engine;
     qDebug() << "the magic number is:" << engine.evaluate("1 + 2").toNumber();
-//! [0]
+    //! [0]
     return 0;
 }
diff --git a/doc/src/snippets/qtscript/registeringobjects/main.cpp b/doc/src/snippets/qtscript/registeringobjects/main.cpp
index 1911442..9dab25a 100644
--- a/doc/src/snippets/qtscript/registeringobjects/main.cpp
+++ b/doc/src/snippets/qtscript/registeringobjects/main.cpp
@@ -44,12 +44,12 @@
 
 int main(int argc, char *argv[])
 {
-//! [0]
+    //! [0]
     QScriptEngine engine;
     QObject *someObject = new MyObject;
     QScriptValue objectValue = engine.newQObject(someObject);
     engine.globalObject().setProperty("myObject", objectValue);
-//! [0]
+    //! [0]
     qDebug() << "myObject's calculate() function returns"
              << engine.evaluate("myObject.calculate(10)").toNumber();
     return 0;
diff --git a/doc/src/snippets/qtscript/registeringvalues/main.cpp b/doc/src/snippets/qtscript/registeringvalues/main.cpp
index 3defc1f..6dc5b7c 100644
--- a/doc/src/snippets/qtscript/registeringvalues/main.cpp
+++ b/doc/src/snippets/qtscript/registeringvalues/main.cpp
@@ -43,10 +43,10 @@
 int main(int argc, char *argv[])
 {
     QScriptEngine engine;
-//! [0]
+    //! [0]
     engine.globalObject().setProperty("foo", 123);
     qDebug() << "foo times two is:" << engine.evaluate("foo * 2").toNumber();
-//! [0]
+    //! [0]
     return 0;
 }
 
-- 
cgit v0.12