Doc tweaks

Minor touchups for the samegame tutorial

5 files changed, 20 insertions, 18 deletions

diff --git a/doc/src/declarative/advtutorial.qdoc b/doc/src/declarative/advtutorial.qdoc
index c796633..60dc0e6 100644
--- a/doc/src/declarative/advtutorial.qdoc
+++ b/doc/src/declarative/advtutorial.qdoc
@@ -47,6 +47,8 @@ This tutorial goes step-by-step through creating a full application using just Q
 It is assumed that you already know basic QML (such as from doing the simple tutorial) and the focus is on showing
 how to turn that knowledge into a complete and functioning application.
 
+This tutorial involves a significant amount of javascript to implement the game logic. An understanding of javascript is helpful to understand the javascript parts of this tutorial, but if you don't understand javascript you can still get a feel for how to integrate QML elements with backend logic which creates and controls them. From the QML perspective, there is little difference between integrating with backend logic written in C++ and backend logic written in javascript.
+
 In this tutorial we recreate, step by step, the Same Game demo in $QTDIR/demos/declarative/samegame.qml.
 The results of the individual steps are in the $QTDIR/examples/declarative/tutorials/samegame directory.
 
diff --git a/doc/src/declarative/advtutorial1.qdoc b/doc/src/declarative/advtutorial1.qdoc
index 66fa607..a96485c 100644
--- a/doc/src/declarative/advtutorial1.qdoc
+++ b/doc/src/declarative/advtutorial1.qdoc
@@ -70,7 +70,7 @@ And here is a simple block:
 
 Since it doesn't do anything yet it's very simple, just an image. As the
 tutorial progresses and the block starts doing things the file will become
-more than just an image. Note that we've set the image to be the size of the itm.
+more than just an image. Note that we've set the image to be the size of the item.
 This will be used later, when we dynamically create and size the block items the image will be scaled automatically
 to the correct size.
 
diff --git a/doc/src/declarative/advtutorial2.qdoc b/doc/src/declarative/advtutorial2.qdoc
index abfdbc6..9fab289 100644
--- a/doc/src/declarative/advtutorial2.qdoc
+++ b/doc/src/declarative/advtutorial2.qdoc
@@ -62,15 +62,15 @@ The \c initBoard function will be hooked up to the new game button soon, and sho
 The \c createBlock function is a lot bigger, and I'll explain it block by block.
 First we ensure that the component has been constructed. QML elements, including composite ones like the \c Block.qml
 that we've written, are never created directly in script. While there is a function to parse and create an arbitrary QML string,
-in the case where you are repeatedly creating the sme item you will want to use the \c createComponent function. \c createComponent is
+in the case where you are repeatedly creating the same item you will want to use the \c createComponent function. \c createComponent is
 a built-in function in the declarative ECMAScript, and returns a component object.
 A component object prepares and stores a QML element (usually a composite element) for easy and efficient use.
 When the component is ready, you can create a new instance of the loaded QML with the \c createObject method.
 If the component is loaded remotely (over HTTP for example) then you will have to wait for the component to finish loading
-before calling \c createObject. Since we don't wait here (the waiting is a syncronous, the component object has a signal to tell
+before calling \c createObject. Since we don't wait here (the waiting is asyncronous, the component object will send a signal to tell
 you when it's done) this code will only work if the block QML is a local file.
 
-As we aren't waiting for he component, the next block of code creates a game block with \c{component.createObject}.
+As we aren't waiting for the component, the next block of code creates a game block with \c{component.createObject}.
 Since there could be an error in the QML file you are trying to load, success is not guaranteed.
 The first bit of error checkign code comes right after \c{createObject()}, to ensure that the object loaded correctly.
 If it did not load correctly the function returns false, but we don't have that hooked up to the main UI to indicate
diff --git a/doc/src/declarative/advtutorial3.qdoc b/doc/src/declarative/advtutorial3.qdoc
index 0d236e4..5ac1be3 100644
--- a/doc/src/declarative/advtutorial3.qdoc
+++ b/doc/src/declarative/advtutorial3.qdoc
@@ -44,7 +44,7 @@
 \example declarative/tutorials/samegame/samegame3
 \title Advanced Tutorial 3 - Implementing the Game Logic
 
-To the \c initBoard function we added clearing the board beforehand, so that clicking new game won't leave the previous game
+First we add to the \c initBoard function clearing of the board before filling it up again, so that clicking new game won't leave the previous game
 lying around in the background. To the \c createComponent function we have added setting the type of the block to a number between
 one and three - it's fundamental to the game logic that the blocks be different types if you want a fun game.
 
@@ -58,33 +58,33 @@ The main change was adding the following game logic functions:
 \endlist
 
 As this is a tutorial about QML, not game design, these functions will not be discussed in detail. The game logic here
-was written in script, but it could have been written in C++ and had these functions exposed just as well (in fact, probably faster).
-The interfacing between these funcions and QML is of interest though. Of these functions, only \c handleClick and \c victoryCheck
+was written in script, but it could have been written in C++ and had these functions exposed in the same way (except probably faster).
+The interfacing of these functions and QML is what we will focus on. Of these functions, only \c handleClick and \c victoryCheck
 interface closely with the QML. Those functions are shown below (the rest are still in the code for this tutorial located at
 \c{$QTDIR/examples/declarative/tutorials/samegame}).
 
 \snippet declarative/tutorials/samegame/samegame3/samegame.js 1
 \snippet declarative/tutorials/samegame/samegame3/samegame.js 2
 
-You'll notice them referring to the \c gameCanvas item. This is an item that has been added to the QML for easy interfacing.
+You'll notice them referring to the \c gameCanvas item. This is an item that has been added to the QML for easier interfacing with the game logic.
 It is placed next to the background image and replaces the background as the item to create the blocks in.
 Its code is shown below:
 
 \snippet declarative/tutorials/samegame/samegame3/samegame.qml 1
 
 This item is the exact size of the board, contains a score property, and a mouse region for input.
-The blocks are now created as its children, and its size is used to determining the board size.
+The blocks are now created as its children, and its size is used to determining the board size, so as to scale to the available screen size.
 Since it needs to bind its size to a multiple of \c tileSize, \c tileSize needs to be moved into a QML property and out of the script file.
-It can still be accessed from the script.
+Note that it can still be accessed from the script.
 
 The mouse region simply calls \c{handleClick()}, which deals with the input events.
 Should those events cause the player to score, \c{gameCanvas.score} is updated.
 The score display text item has also been changed to bind its text property to \c{gamecanvas.score}.
 Note that if score was a global variable in the \c{samegame.js} file you could not bind to it. You can only bind to QML properties.
 
-\c victoryCheck() mostly just updates score. But it also pops up a dialog saying \e {Game Over} when the game is over.
+\c victoryCheck() primarily updates the score variable. But it also pops up a dialog saying \e {Game Over} when the game is over.
 In this example we wanted a pure-QML, animated dialog, and since QML doesn't contain one, we wrote our own.
-Below is the code for the \c Dialog element, note how it's designed so as to be quite usable imperatively from within the script file:
+Below is the code for the \c Dialog element, note how it's designed so as to be usable imperatively from within the script file (via the functions and signals):
 
 \snippet declarative/tutorials/samegame/samegame3/Dialog.qml 0
 
@@ -107,7 +107,7 @@ And the code for the block:
 
 \snippet declarative/tutorials/samegame/samegame3/Block.qml 0
 
-The game works, but it's a little boring right now. Where's the smooth animated transitions? Where's the high scores?
+The game works, but it's a little boring right now. Where are the smooth animated transitions? Where are the high scores?
 If you were a QML expert you could have written these in for the first iteration, but in this tutorial they've been saved
 until the next chapter - where your application becomes alive!
 
diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc
index f4724d8..2599e32 100644
--- a/doc/src/declarative/advtutorial4.qdoc
+++ b/doc/src/declarative/advtutorial4.qdoc
@@ -71,7 +71,7 @@ parameters specified). This is shown in the below snippet of code from \c Block.
 We also have to change the \c{samegame.js} code, so that wherever it was setting the \c x or \c y it now sets \c targetX and \c targetY
 (including when creating the block). This simple change is all you need to get spring moving blocks that no longer teleport
 around the board. If you try doing just this though, you'll notice that they now never jump from one point to another, even in
-the initialization! This gives an odd effect of having them all jump out of the corner (0,0) on start up. We'd rather that they
+the initialization! This gives an odd effect of having them all slide out of the corner (0,0) on start up. We'd rather that they
 fall down from the top in rows. To do this, we disable the \c x follow (but not the \c y follow) and only enable it after we've set
 the \c x in the \c createBlock function. The above snippet now becomes:
 
@@ -84,7 +84,7 @@ image's opacity, like so:
 
 \snippet declarative/tutorials/samegame/samegame4/content/BoomBlock.qml 2
 
-Note that the \c{opacity: 0} makes it start out transparent. We could set the opacity in the script file when we create the blocks,
+Note that the \c{opacity: 0} makes it start out transparent. We could set the opacity in the script file when we create and destroy the blocks,
 but instead we use states (as this is useful for the next animation we'll implement). The below snippet is set on the root
 element of \c{Block.qml}:
 \code
@@ -129,7 +129,7 @@ if they exit this dialog without entering it they have a way to opt out of posti
 
 For offline storage, we use the HTML 5 offline storage javascript API to maintain a persistant SQL database unique to this application. This first line in this function calls the function for the web-based high scores, described later, if it has been setup. Next we create an offline storage database for the high scores using openDatabase and prepare the data and SQL query that we want to use to save it. The offline storage API uses SQL queries for data manipulation and retrival, and in the db.transaction call we use three SQL queries to initialize the database (if necessary), and then add to and retrieve high scores. To use the returned data, we turn it into a string with one line per row returned, and show a dialog containing that string. For a more detailed explanation of the offline storage API in QML, consult the global object documentation.
 
-This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL.
+This is one way of storing and displaying high scores locally, but not the only way. A more complex alternative would have been to create a high score dialog component, and pass the results to it for processing and display (instead of resusing the Dialog). This would allow a more themable dialog that could present the high scores better. If your QML is the UI for a C++ application, you could also have passed the score to a C++ function to store it locally in a variety of ways, including a simple format without SQL or in another SQL database.
 
 \section2 Web-based High Scores
 
@@ -143,7 +143,7 @@ if the player entered their name we can send the data to the web service in the
 \snippet declarative/tutorials/samegame/samegame4/content/samegame.js 1
 
 This is the same \c XMLHttpRequest() as you'll find in browser javascript, and can be used in the same way to dynamically get XML
-or QML from the web service to display the high scores. We don't worry about the response here though, we just post the high
+or QML from the web service to display the high scores. We don't worry about the response in this case, we just post the high
 score data to the web server. If it had returned a QML file (or a URL to a QML file) you could instantiate it in much the same
 way as you did the blocks.
 
@@ -152,7 +152,7 @@ makes it very easy to fetch and display XML based data such as RSS in a QML appl
 
 By following this tutorial you've now ben shown how to write a fully functional application in QML, with the application logic
 written in a script file and with both many fluid animations and being web-enabled. Congratulations, you should now be skilled
-enough to write your own QML applications.
+enough to write entire applications in QML.
 
 [Previous: \l {Advanced Tutorial 3 - Implementing the Game Logic}] [\l {advtutorial.html}{Advanced Tutorial}]
 */