Example QtHangman: Add documentation

Change-Id: I569c7e739d175f26a212fbf8aa68a6faf07c99fb
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>
Reviewed-by: Andy Nichols <andy.nichols@digia.com>

6 files changed, 71 insertions, 6 deletions

diff --git a/examples/purchasing/qthangman/doc/images/qthangman-example.png b/examples/purchasing/qthangman/doc/images/qthangman-example.png
new file mode 100644
index 0000000..df54b8d
--- /dev/null
+++ b/examples/purchasing/qthangman/doc/images/qthangman-example.png
diff --git a/examples/purchasing/qthangman/doc/images/qthangman-store-example.png b/examples/purchasing/qthangman/doc/images/qthangman-store-example.png
new file mode 100644
index 0000000..99583b5
--- /dev/null
+++ b/examples/purchasing/qthangman/doc/images/qthangman-store-example.png
diff --git a/examples/purchasing/qthangman/doc/src/qthangman.qdoc b/examples/purchasing/qthangman/doc/src/qthangman.qdoc
new file mode 100644
index 0000000..7a779d1
--- /dev/null
+++ b/examples/purchasing/qthangman/doc/src/qthangman.qdoc
@@ -0,0 +1,61 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \title Qt Purchasing Examples - QtHangman
+    \example qthangman
+    \brief QtHangman is an example that demonstrates how to use the Qt Purchasing API with Qt Quick.
+    \image qthangman-example.png
+    \ingroup qtpurchasing-examples
+
+    QtHangman is a complete mobile application that demonstrates how it is possible to offer in-app products inside a Qt application in a cross-platform manner.
+
+
+    In-app purchasing can be added to a Qt Mobile application by first adding a Store object.  In QtHangman the Store object
+    is created by the MainView component that is loaded on application startup.
+    \snippet qthangman/qml/qthangman/MainView.qml 0
+
+    QtHangman defines a component for displaying a store for purchasing in-app products made available.  These products must be first
+    registered with the store object we created above in MainView.  There are two products available, the first being a consumable type.
+    \snippet qthangman/qml/qthangman/StoreView.qml 0
+    This consumable product provides 100 additional vowels to be used when guessing words in the game.  When it is successfully
+    purchased we update the state of the application to include 100 additional vowels. Then we call finalize on the transaction object to
+    confirm to the platform store that the consumable product has been provided.
+
+    The second product is a non-consumable type that will unlock vowels permanently in the future.  In addition to updating the application
+    state on purchase, we must make sure to provide a way to restore this purchase on other devices used by the end user.  In this case
+    we create a signal handler for onPurchaseRestored.
+    \snippet qthangman/qml/qthangman/StoreView.qml 1
+
+    \image qthangman-store-example.png
+    In additon to registering the products, we also provide an interface to actually purchase the registered product.  QtHangman defines a
+    custom component called StoreItem to display and handle the purchasing interaction.
+    \snippet qthangman/qml/qthangman/StoreView.qml 1
+    The StoreItem component will display the product data that is queried from the platform's store, and will call the purchase() method on the
+    product when it is clicked by the user.
+    \snippet qthangman/qml/qthangman/StoreItem.qml 0
+*/
diff --git a/examples/purchasing/qthangman/qml/qthangman/MainView.qml b/examples/purchasing/qthangman/qml/qthangman/MainView.qml
index c568a53..7138676 100644
--- a/examples/purchasing/qthangman/qml/qthangman/MainView.qml
+++ b/examples/purchasing/qthangman/qml/qthangman/MainView.qml
@@ -76,8 +76,9 @@ Item {
         anchors.fill: topLevel
         initialItem: Qt.resolvedUrl("GameView.qml")
     }
-
+    // ![0]
     Store {
         id: iapStore
     }
+    // ![0]
 }
diff --git a/examples/purchasing/qthangman/qml/qthangman/StoreItem.qml b/examples/purchasing/qthangman/qml/qthangman/StoreItem.qml
index 101fe95..93cf660 100644
--- a/examples/purchasing/qthangman/qml/qthangman/StoreItem.qml
+++ b/examples/purchasing/qthangman/qml/qthangman/StoreItem.qml
@@ -54,7 +54,7 @@ Rectangle {
     color: "white"
 
     height: titleText.contentHeight + descriptionText.contentHeight + topLevel.globalMargin * 2
-
+    // ![0]
     Text {
         id: titleText
         text: product.title
@@ -103,6 +103,7 @@ Rectangle {
             storeItem.state = "NORMAL";
         }
     }
+    // ![0]
 
     Rectangle {
         id: pendingRect
diff --git a/examples/purchasing/qthangman/qml/qthangman/StoreView.qml b/examples/purchasing/qthangman/qml/qthangman/StoreView.qml
index 120f238..cdd3a01 100644
--- a/examples/purchasing/qthangman/qml/qthangman/StoreView.qml
+++ b/examples/purchasing/qthangman/qml/qthangman/StoreView.qml
@@ -56,7 +56,7 @@ Item {
         anchors.right: parent.right
         anchors.left: parent.left
         spacing: topLevel.globalMargin
-
+        // ![2]
         StoreItem {
             product: product100Vowels
             width: parent.width
@@ -66,7 +66,7 @@ Item {
             product: productUnlockVowels
             width: parent.width
         }
-
+        // ![2]
     }
 
     SimpleButton {
@@ -82,7 +82,7 @@ Item {
         }
     }
 
-
+    // ![0]
     Product {
         id: product100Vowels
         store: iapStore
@@ -103,7 +103,8 @@ Item {
             transaction.finalize();
         }
     }
-
+    // ![0]
+    // ![1]
     Product {
         id: productUnlockVowels
         type: Product.Unlockable
@@ -132,5 +133,6 @@ Item {
             pageStack.pop();
         }
     }
+    // ![1]
 
 }