Add documentation to the Sub-attaq example

Task-number: QTBUG-89834
Change-Id: I75198b11f75a202bba3843a57e94e8f5db259210
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit e6db5a7e0e74b153ba9cbe1d376bd7c49cfdbe49)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

7 files changed, 100 insertions, 21 deletions

diff --git a/examples/statemachine/animation/sub-attaq/graphicsscene.cpp b/examples/statemachine/animation/sub-attaq/graphicsscene.cpp
index d8c068a..cbc04c8 100644
--- a/examples/statemachine/animation/sub-attaq/graphicsscene.cpp
+++ b/examples/statemachine/animation/sub-attaq/graphicsscene.cpp
@@ -74,6 +74,7 @@
 GraphicsScene::GraphicsScene(int x, int y, int width, int height, Mode mode, QObject *parent)
     : QGraphicsScene(x, y, width, height, parent), mode(mode), boat(new Boat)
 {
+//![2]
     PixmapItem *backgroundItem = new PixmapItem(QStringLiteral("background"), mode);
     backgroundItem->setZValue(1);
     backgroundItem->setPos(0,0);
@@ -97,6 +98,7 @@ GraphicsScene::GraphicsScene(int x, int y, int width, int height, Mode mode, QOb
     addItem(boat);
     boat->setPos(this->width()/2, sealLevel() - boat->size().height());
     boat->hide();
+//![2]
 
     //Parse the xml that contains all data of the game
     QXmlStreamReader reader;
@@ -173,6 +175,7 @@ void GraphicsScene::setupScene(QAction *newAction, QAction *quitAction)
         fadeAnim->setEasingCurve(QEasingCurve::OutQuad);
     }
 
+//![3]
     QStateMachine *machine = new QStateMachine(this);
 
     //This state is when the player is playing
@@ -207,6 +210,7 @@ void GraphicsScene::setupScene(QAction *newAction, QAction *quitAction)
 
     //We reach the final state, then we quit
     connect(machine, &QStateMachine::finished, qApp, &QApplication::quit);
+//![3]
 }
 
 void GraphicsScene::addItem(Bomb *bomb)
diff --git a/examples/statemachine/animation/sub-attaq/main.cpp b/examples/statemachine/animation/sub-attaq/main.cpp
index 9b28d8c..c11664b 100644
--- a/examples/statemachine/animation/sub-attaq/main.cpp
+++ b/examples/statemachine/animation/sub-attaq/main.cpp
@@ -52,6 +52,7 @@
 
 #include "mainwindow.h"
 
+//![0]
 int main(int argc, char *argv[])
 {
     QApplication app(argc, argv);
@@ -62,3 +63,4 @@ int main(int argc, char *argv[])
 
     return app.exec();
 }
+//![0]
diff --git a/examples/statemachine/animation/sub-attaq/mainwindow.cpp b/examples/statemachine/animation/sub-attaq/mainwindow.cpp
index 0c152c9..9b434c6 100644
--- a/examples/statemachine/animation/sub-attaq/mainwindow.cpp
+++ b/examples/statemachine/animation/sub-attaq/mainwindow.cpp
@@ -62,6 +62,7 @@
 MainWindow::MainWindow(QWidget *parent)
     : QMainWindow(parent)
 {
+//![1]
     QMenu *file = menuBar()->addMenu(tr("&File"));
 
     QAction *newAction = file->addAction(tr("New Game"));
@@ -81,4 +82,5 @@ MainWindow::MainWindow(QWidget *parent)
     view->setAlignment(Qt::AlignLeft | Qt::AlignTop);
     scene->setupScene(newAction, quitAction);
     setCentralWidget(view);
+//![1]
 }
diff --git a/examples/statemachine/animation/sub-attaq/states.cpp b/examples/statemachine/animation/sub-attaq/states.cpp
index 3142f2c..3758f68 100644
--- a/examples/statemachine/animation/sub-attaq/states.cpp
+++ b/examples/statemachine/animation/sub-attaq/states.cpp
@@ -90,53 +90,54 @@ void PlayState::onEntry(QEvent *)
         delete machine;
     }
 
+//![4]
     machine = new QStateMachine;
 
-    //This state is when player is playing
+    //This state is active when the player is playing
     LevelState *levelState = new LevelState(scene, this, machine);
 
-    //This state is when the player is actually playing but the game is not paused
+    //This state is active when the player is actually playing but the game is not paused
     QState *playingState = new QState(levelState);
     levelState->setInitialState(playingState);
 
-    //This state is when the game is paused
+    //This state is active when the game is paused
     PauseState *pauseState = new PauseState(scene, levelState);
 
-    //We have one view, it receive the key press event
+    //We have one view, it receives the key press events
     QKeyEventTransition *pressPplay = new QKeyEventTransition(scene->views().at(0), QEvent::KeyPress, Qt::Key_P);
     pressPplay->setTargetState(pauseState);
     QKeyEventTransition *pressPpause = new QKeyEventTransition(scene->views().at(0), QEvent::KeyPress, Qt::Key_P);
     pressPpause->setTargetState(playingState);
 
-    //Pause "P" is triggered, the player pause the game
+    //Pause "P" is triggered, when the player pauses the game
     playingState->addTransition(pressPplay);
 
-    //To get back playing when the game has been paused
+    //To get back to playing when the game has been paused
     pauseState->addTransition(pressPpause);
 
-    //This state is when player have lost
+    //This state is active when player has lost
     LostState *lostState = new LostState(scene, this, machine);
 
-    //This state is when player have won
+    //This state is active when player has won
     WinState *winState = new WinState(scene, this, machine);
 
-    //The boat has been destroyed then the game is finished
+    //If boat has been destroyed then the game is finished
     levelState->addTransition(scene->boat, &Boat::boatExecutionFinished,lostState);
 
-    //This transition check if we won or not
+    //This transition checks if we have won or not
     WinTransition *winTransition = new WinTransition(scene, this, winState);
 
-    //The boat has been destroyed then the game is finished
+    //If boat has been destroyed then the game is finished
     levelState->addTransition(winTransition);
 
-    //This state is an animation when the score changed
+    //This state is for an animation when the score changes
     UpdateScoreState *scoreState = new UpdateScoreState(levelState);
 
-    //This transition update the score when a submarine die
+    //This transition updates the score when a submarine is destroyed
     UpdateScoreTransition *scoreTransition = new UpdateScoreTransition(scene, this, levelState);
     scoreTransition->setTargetState(scoreState);
 
-    //The boat has been destroyed then the game is finished
+    //If the boat has been destroyed then the game is finished
     playingState->addTransition(scoreTransition);
 
     //We go back to play state
@@ -148,16 +149,18 @@ void PlayState::onEntry(QEvent *)
     //Final state
     QFinalState *finalState = new QFinalState(machine);
 
-    //This transition is triggered when the player press space after completing a level
+    //This transition is triggered when the player presses space after completing a level
     CustomSpaceTransition *spaceTransition = new CustomSpaceTransition(scene->views().at(0), this, QEvent::KeyPress, Qt::Key_Space);
     spaceTransition->setTargetState(levelState);
     winState->addTransition(spaceTransition);
 
-    //We lost we should reach the final state
+    //We lost so we should reach the final state
     lostState->addTransition(lostState, &QState::finished, finalState);
 
     scene->textInformationItem->hide();
     machine->start();
+//![4]
+
 }
 
 LevelState::LevelState(GraphicsScene *scene, PlayState *game, QState *parent) : QState(parent), scene(scene), game(game)
@@ -168,6 +171,7 @@ void LevelState::onEntry(QEvent *)
     initializeLevel();
 }
 
+//![5]
 void LevelState::initializeLevel()
 {
     //we re-init the boat
@@ -199,6 +203,7 @@ void LevelState::initializeLevel()
         }
     }
 }
+//![5]
 
 /** Pause State */
 PauseState::PauseState(GraphicsScene *scene, QState *parent) : QState(parent), scene(scene)
diff --git a/examples/statemachine/doc/images/sub-attaq-graphicsscene-chart.png b/examples/statemachine/doc/images/sub-attaq-graphicsscene-chart.png
new file mode 100644
index 0000000..86f4650
--- /dev/null
+++ b/examples/statemachine/doc/images/sub-attaq-graphicsscene-chart.png
diff --git a/examples/statemachine/doc/images/sub-attaq-playstate-chart.png b/examples/statemachine/doc/images/sub-attaq-playstate-chart.png
new file mode 100644
index 0000000..37e7ff7
--- /dev/null
+++ b/examples/statemachine/doc/images/sub-attaq-playstate-chart.png
diff --git a/examples/statemachine/doc/src/sub-attaq.qdoc b/examples/statemachine/doc/src/sub-attaq.qdoc
index 002b50a..c65d2ba 100644
--- a/examples/statemachine/doc/src/sub-attaq.qdoc
+++ b/examples/statemachine/doc/src/sub-attaq.qdoc
@@ -30,12 +30,78 @@
     \title Sub-Attaq
     \ingroup examples-qtstatemachine
 
-    \brief This example shows Qt's ability to combine \l{The Animation Framework}{the animation framework}
-    and \l{Qt State Machine Overview}{the state machine framework} to create a game.
+    \brief This example shows Qt's ability to combine
+    \l{The Animation Framework}{the animation framework}
+    and \l{Qt State Machine Overview}{the state machine framework} to create a
+    game.
 
     \image sub-attaq-demo.png
 
-    The purpose of the game is to destroy all submarines to win the current level.
-    The boat can be controlled using left and right keys. To fire a bomb you can press
-    up and down keys.
+    The purpose of the game is to destroy all submarines to win the current
+    level. The boat can be controlled using left and right keys. To fire a bomb
+    you can press the up and down keys.
+
+    \section1 The \c main() Function
+
+    \snippet animation/sub-attaq/main.cpp 0
+
+    The MainWindow instance is created and shown.
+
+    \section1 The \c MainWindow Class
+
+    \snippet animation/sub-attaq/mainwindow.cpp 1
+
+    MainWindow extends QMainWindow and contains the GraphicsScene instance. It
+    creates and sets up the menu bar as well.
+
+    \section1 The \c GraphicsScene Class
+
+    There are several state machines in the application. The \c GraphicsScene
+    state machine handles states related to events outside the actual game scene
+    like the letter animation in the beginning.
+
+    \section2 The \c GraphicsScene Constructor
+
+    \snippet animation/sub-attaq/graphicsscene.cpp 2
+
+    The \c GraphicsScene class contains the background images and the score and
+    level information texts.
+
+    \section2 \c The setupScene Method
+
+    \snippet animation/sub-attaq/graphicsscene.cpp 3
+
+    The four state machine states are created with sequential transitions from
+    one to the next. The \c gameState also has a transition that is triggered
+    by \c newAction, the new game menu item, or its shortcut key at any point
+    in the application. The \c gameState state is an instance of the
+    \c PlayState class.
+
+    \image sub-attaq-graphicsscene-chart.png
+
+    \section1 The \c PlayState Class
+
+    The \c PlayState class is a QState derived class that handles the state when
+    the game is in progress.
+
+    \snippet animation/sub-attaq/states.cpp 4
+
+    The \c PlayState state machine handles higher level game logic like pausing
+    the game and updating the score.
+
+    \image sub-attaq-playstate-chart.png
+
+    The \c playingState state is a QState instance that is active while the user
+    is actively playing the game. The \c pauseState is set up with transitions
+    to and from \c playingState, which are triggered by pressing the p key.
+    The \c lostState is created with a transition to it, which is triggered when
+    the boat is destroyed. The \c winState is also created here with a
+    transition to and from the \c levelState.
+
+    \section1 The \c LevelState Class
+
+    \snippet animation/sub-attaq/states.cpp 5
+
+    The components of the scene are initialized based on what level the player
+    has reached.
 */