From dd871bf6208821ab9852680a338133accbfdedd7 Mon Sep 17 00:00:00 2001
From: Bea Lam <bea.lam@nokia.com>
Date: Wed, 28 Jul 2010 16:54:38 +1000
Subject: Component docs

Task-number: QTBUG-12447
---
 doc/src/snippets/declarative/component.qml    | 60 +++++++++++++++++++++++++++
 src/declarative/qml/qdeclarativecomponent.cpp | 30 ++++----------
 2 files changed, 69 insertions(+), 21 deletions(-)
 create mode 100644 doc/src/snippets/declarative/component.qml

diff --git a/doc/src/snippets/declarative/component.qml b/doc/src/snippets/declarative/component.qml
new file mode 100644
index 0000000..09c4aa2
--- /dev/null
+++ b/doc/src/snippets/declarative/component.qml
@@ -0,0 +1,60 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+//![0]
+import Qt 4.7
+
+Item {
+    width: 100; height: 100
+
+    Component {
+        id: redSquare
+
+        Rectangle {
+            color: "red"
+            width: 10
+            height: 10
+        }
+    }
+
+    Loader { sourceComponent: redSquare }
+    Loader { sourceComponent: redSquare; x: 20 }
+}
+//![0]
diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index e8e237f..1d48b1a 100644
--- a/src/declarative/qml/qdeclarativecomponent.cpp
+++ b/src/declarative/qml/qdeclarativecomponent.cpp
@@ -115,26 +115,10 @@ class QByteArray;
     a small component within a QML file, or for defining a component that logically 
     belongs with other QML components within a file.
 
-    For example, here is a component that is used by multiple \l Loader objects:
+    For example, here is a component that is used by multiple \l Loader objects.
+    It contains a top level \l Rectangle item:
 
-    \qml
-    Item {
-        width: 100; height: 100
-
-        Component {
-            id: redSquare
-
-            Rectangle {
-                color: "red"
-                width: 10
-                height: 10
-            }
-        }
-
-        Loader { sourceComponent: redSquare }
-        Loader { sourceComponent: redSquare; x: 20 }
-    }
-    \endqml
+    \snippet doc/src/snippets/declarative/component.qml 0
 
     Notice that while a \l Rectangle by itself would be automatically 
     rendered and displayed, this is not the case for the above rectangle
@@ -143,12 +127,16 @@ class QByteArray;
     file, and is not loaded until requested (in this case, by the
     two \l Loader objects).
 
+    A Component cannot contain anything other
+    than an \c id and a single top level item. While the \c id is optional,
+    the top level item is not; you cannot define an empty component.
+
     The Component element is commonly used to provide graphical components
     for views. For example, the ListView::delegate property requires a Component
     to specify how each list item is to be displayed.
 
-    Component objects can also be dynamically generated using
-    \l{Qt::createComponent()}{Qt.createComponent()}.
+    Component objects can also be dynamically created using
+    \l{QML:Qt::createComponent()}{Qt.createComponent()}.
 */
 
 /*!
-- 
cgit v0.12