Merge lp:~kevin-wright-1/u1db-qt/qdoc-examples-april-23-2013-i into lp:u1db-qt

[Kevin Wright]

Modified example qml files to reduce number of warnings from qdoc. Changed each example's tutorial file from \example to \page and modified all \qml tags to \code tags.

Modified example qml files to reduce number of warnings from qdoc. Changed each example's tutorial file from \example to \page and modified all \qml tags to \code tags.

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

PASSED: Continuous integration, rev:78
http://91.189.93.125:8080/job/u1db-qt-ci/13/
Executed test runs:
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-quantal-amd64-ci/13
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-raring-amd64-ci/13

Click here to trigger a rebuild:
http://91.189.93.125:8080/job/u1db-qt-ci/13/rebuild

review: Approve (continuous-integration)

[Cris Dywan (kalikiana)]

Very sweet!

review: Approve

=== modified file 'documentation/concepts.qdoc'
--- documentation/concepts.qdoc	2013-04-22 11:28:15 +0000
+++ documentation/concepts.qdoc	2013-04-23 11:57:27 +0000
@@ -17,8 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-
-
 /*!
 \page concepts.html
 \title Design Concepts

=== modified file 'examples/u1db-qt-example-1/u1db-qt-example-1.qdoc'
--- examples/u1db-qt-example-1/u1db-qt-example-1.qdoc	2013-04-08 10:32:14 +0000
+++ examples/u1db-qt-example-1/u1db-qt-example-1.qdoc	2013-04-23 11:57:27 +0000
@@ -19,6 +19,6 @@
 
 /*!
 
-\example u1db-qt-example-1
+\page  u1db-qt-tutorial-1.html
 
 */

=== modified file 'examples/u1db-qt-example-2/u1db-qt-example-2.qdoc'
--- examples/u1db-qt-example-2/u1db-qt-example-2.qdoc	2013-04-08 10:32:14 +0000
+++ examples/u1db-qt-example-2/u1db-qt-example-2.qdoc	2013-04-23 11:57:27 +0000
@@ -19,6 +19,6 @@
 
 /*!
 
-\example u1db-qt-example-2
+\page  u1db-qt-tutorial-2.html
 
 */

=== modified file 'examples/u1db-qt-example-2b/u1db-qt-example-2b.qdoc'
--- examples/u1db-qt-example-2b/u1db-qt-example-2b.qdoc	2013-04-08 10:32:14 +0000
+++ examples/u1db-qt-example-2b/u1db-qt-example-2b.qdoc	2013-04-23 11:57:27 +0000
@@ -19,6 +19,6 @@
 
 /*!
 
-\example u1db-qt-example-2b
+\page  u1db-qt-tutorial-2b.html
 
 */

=== modified file 'examples/u1db-qt-example-3/u1db-qt-example-3.qdoc'
--- examples/u1db-qt-example-3/u1db-qt-example-3.qdoc	2013-04-08 10:32:14 +0000
+++ examples/u1db-qt-example-3/u1db-qt-example-3.qdoc	2013-04-23 11:57:27 +0000
@@ -19,6 +19,6 @@
 
 /*!
 
-\example u1db-qt-example-3
+\page  u1db-qt-tutorial-3.html
 
 */

=== modified file 'examples/u1db-qt-example-4/u1db-qt-example-4.qdoc'
--- examples/u1db-qt-example-4/u1db-qt-example-4.qdoc	2013-04-08 10:32:14 +0000
+++ examples/u1db-qt-example-4/u1db-qt-example-4.qdoc	2013-04-23 11:57:27 +0000
@@ -19,6 +19,6 @@
 
 /*!
 
-\example u1db-qt-example-4
+\page  u1db-qt-tutorial-4.html
 
 */

=== modified file 'examples/u1db-qt-example-5/u1db-qt-example-5.qdoc'
--- examples/u1db-qt-example-5/u1db-qt-example-5.qdoc	2013-04-12 08:06:46 +0000
+++ examples/u1db-qt-example-5/u1db-qt-example-5.qdoc	2013-04-23 11:57:27 +0000
@@ -1,6 +1,6 @@
 /*!
 
-\example u1db-qt-example-5
+\page  u1db-qt-tutorial-5.html
 
 \title U1Db-Qt Index Tutorial
 
@@ -20,12 +20,12 @@
 
 A Database is very simple to create. It only needs an id and a path where the file will be created. A Database is a model, which can be used by elements, such as the ListView further in this example.
 
-\qml
+\code
 U1db.Database {
     id: aDatabase
     path: "aDatabase4"
 }
-\endqml
+\endcode
 
 \section1 The Document Element
 
@@ -37,39 +37,39 @@
 
 This example of a very simple Document will not initially do anything, until more properties are added and defined:
 
-\qml
+\code
 U1db.Document {
     id: aDocument1
     docId: 'helloworld1'
 }
-\endqml
+\endcode
 
 A basic but still practical Document definition contains several essential properties. In addition to 'id' and 'docId' (discussed above), the 'database', 'create', and 'defaults' properties are also very important, and are introduced below.
 
 The 'database' property ensures that the Document is attached to an already defined (or possibly soon to be defined one) identified by its id (in this case 'aDatabase'). For example:
 
-\qml
+\code
 U1db.Document {
     id: aDocument1
     database: aDatabase
     docId: 'helloworld1'
 }
-\endqml
+\endcode
 
 Should the Database not already contain a Document with the same docId ('hellowworld1' in this example) when a 'create' property is present and set to true it will be generated. For example:
 
-\qml
+\code
 U1db.Document {
     id: aDocument1
     database: aDatabase
     docId: 'helloworld1'
     create: true
 }
-\endqml
+\endcode
 
 However, the Document still requires some data to be useful, which is what the 'defaults' property provides. The value of 'defaults' is a map of data that will be stored in the database (again when the create property is et to true). It contain key:value pairs, where the value can be a string, number, or nested object (e.g. additional fields, lists). For example:
 
-\qml
+\code
 U1db.Document {
     id: aDocument1
     database: aDatabase
@@ -77,11 +77,11 @@
     create: true
     defaults:{"hello": { "world": { "message":"Hello World", "id": 1 } } }
 }
-\endqml
+\endcode
 
 As mentioned above, lists can also be nested in Document data. Lists provide a convenient method for producing multiple instances of the same key (AKA 'field' or 'sub-field'). The example code below shows valid use of the 'message' and 'id' sub-fields multiple times within the same object.
 
-\qml
+\code
 U1db.Document {
     id: aDocument2
     database: aDatabase
@@ -92,11 +92,11 @@
                             { "message":"Hello World", "id": 2.5 }
                         ] } }
 }
-\endqml
+\endcode
 
 When the default Javascript Object Notation itself is formatted with appropriate line breaks and indentation, it becomes easier to visualize an embedded list, containing sub-fields 'message' and 'id' (and their respective values):
 
-\qml
+\code
 {"hello":
     { "world":
         [
@@ -105,14 +105,14 @@
         ]
     }
 }
-\endqml
+\endcode
 
 In dot notation these sub-fields are represented by 'hello.world.message' and 'hello.world.id' respectively. Later in this tutorial these will be utilized within the 'expression' property of U1Db-Qt's Index element, in close collaboration with a QML ListView's delegates.
 
 
 Normally when a docId already exists in a database, and when the set flag is set to true, the value in 'defaults' will be ignored (and the existing data in the database will remain untouched). Sometimes a developer needs to easily overwrite the data in an existing document. The 'contents' property can be used for just that purpose. When 'contents' is defined, its value will replace existing data in the database, for the document identified by the docId. In addition, 'contents' can be used to add new documents, in the same way as the 'create: true' + 'defaults' combination does; in other words, if the document defined by 'docId' does not exist it will be created.
 
-\qml
+\code
 U1db.Document {
     id: aDocument3
     database: aDatabase
@@ -123,11 +123,11 @@
                             { "message":"Hello World", "id": 3.66 }
                         ] } }
 }
-\endqml
+\endcode
 
 If 'defaults' exists, 'create' is set to 'true' (or 'false' for that matter) and 'contents' is also defined, it is the latter that takes precidence. In other words, 'create' and 'defaults' will be ignored. The following example demonstrates this scenario:
 
-\qml
+\code
 U1db.Document {
     id: aDocument3
     database: aDatabase
@@ -140,18 +140,18 @@
                                     { "message":"Hello World", "id": 3.66 }
                         ] } }
 }
-\endqml
+\endcode
 
 This snippet simply represents the absence of the 'create' property, which is synonymous with 'create: false'. The Document can still be recognized within the application, but until applicable properties (such as those outlined above) are added and/or modified then nothing will be added or modified in the database, and this instance may have very little practical value.
 
-\qml
+\code
 U1db.Document {
     id: aDocument4
     database: aDatabase
     docId: 'helloworld4'
     defaults:{"hello": { "world": { "message":"Hello World", "id": 4 } } }
 }
-\endqml
+\endcode
 
 \section3 Samples of Stored Documents
 
@@ -237,33 +237,33 @@
 
 The Index element requires both a unique 'id' and a pointer to a 'database' in order to begin becoming useful, as demonstrated here:
 
-\qml
+\code
 U1db.Index{
     database: aDatabase
     id: by_helloworld
 }
-\endqml
+\endcode
 
 In the future, the Index element will support on disk storage of appropriate results / data. At the present time only in memory indexing is done, but once the storing capability is implemented, defining and identifying it is as simple as using the 'name' property (which will be stored in the database along with the relvent data that goes with it). The snippet below shows the use of the 'name' property:
 
-\qml
+\code
 U1db.Index{
     database: aDatabase
     id: by_helloworld
     //name: "by-helloworld"
 }
-\endqml
+\endcode
 
 The Index element describes, using dot notation, the fields and sub-fields where the developer expects to find information. That information is defined in a list, and added as the value for the 'expression' property. The list can contain one or more entries, as exemplified here (the property is commented out due to its current status):
 
-\qml
+\code
 U1db.Index{
     database: aDatabase
     id: by_helloworld
     //name: "by-helloworld"
     expression: ["hello.world.id","hello.world.message"]
 }
-\endqml
+\endcode
 
 \section2 The QueryElement
 
@@ -273,43 +273,43 @@
 
 In order to fulfil its duties as a bridge to an Index (and Database), the 'index' property must point to an Index element, identified by its 'id'. For example:
 
-\qml
+\code
 U1db.Query{
     id: aQuery
     index: by_helloworld
 }
-\endqml
+\endcode
 
 While Index helps to filter data based on 'where' it is located (e.g. field.sub-field), Query helps determine the additional set of criteria for 'what' is being searched for. The intent of the 'query' property is to provide the mechanism for defnining the search criteria, but at the time of writing that functionality is not yet available. However, once the implementation is in place, using it is only requires defining the property's value (e.g. "Hello World"). Wild card searches using '*' are supported, which is the default query (i.e. if 'query' is not set it is assumed to be '*'). For example (the property is commented out due to its current status):
 
-\qml
+\code
 U1db.Query{
     id: aQuery
     index: by_helloworld
     //query: "*"
 }
-\endqml
+\endcode
 
 When the 'query' property becomes available, only wildcard search definitions for "starts with" will be suppoprted. Thus the following would be supported:
 
-\qml
+\code
 U1db.Query{
     id: aQuery
     index: by_helloworld
     //query: "Hello*"
 }
-\endqml
+\endcode
 
 
 But this would not:
 
-\qml
+\code
 U1db.Query{
     id: aQuery
     index: by_helloworld
     //query: "*World"
 }
-\endqml
+\endcode
 
 Note: again, the 'query' property is commented out in the above two snippets due to its current status
 
@@ -321,19 +321,19 @@
 
 This simple snippet represents how to attach a ListModel to a ListView. In this instance the model 'aQuery' is representative of the Query + Index combination defined earlier:
 
-\qml
+\code
 ListView {
     width: units.gu(45)
     height: units.gu(80)
     model: aQuery
 }
-\endqml
+\endcode
 
 \section4 Data and Delegates
 
 How a model and ListView + delegates work together is a common QML concept, and not specific to U1Db-Qt. However, the asynchronous nature of this relationship is important to understand. When using QML ListView, delegates will be created based on particular properties such as the size of the application window, ListView, and delegate itself (amongst other factors). Each delegate can then represent a Document retrieved from the Database based on the record's index. This example demonstrates some of the property definitions that contribute to determining the number of delegates a ListView will contain:
 
-\qml
+\code
 ListView {
     width: units.gu(45)
     height: units.gu(80)
@@ -344,7 +344,7 @@
     }
 
 }
-\endqml
+\endcode
 
 
 When the number of Documents is less than or equal to the number of delegates then there is a one to one mapping of index to delegate (e.g. the first delegate will represent the Document with an index = 0; the second, index = 1; and so on).
@@ -353,7 +353,7 @@
 
 The following snippet, which modifies the above delegate definition, could demonstrate this effect if there were enough Documents to do so (i.e. some number greater than the number of delegates):
 
-\qml
+\code
 ListView {
     width: units.gu(45)
     height: units.gu(80)
@@ -365,11 +365,11 @@
     }
 
 }
-\endqml
+\endcode
 
 The object called 'contents' contains one or more properties. This example demonstrates the retrieval of data based on the U1db.Index defined earlier (id: by-helloworld). In this instance the Index contained two expressions simultaniously, "hello.world.id" and "hello.world.message"
 
-\qml
+\code
 ListView {
     width: units.gu(45)
     height: units.gu(80)
@@ -381,6 +381,6 @@
     }
 
 }
-\endqml
+\endcode
 
 */