Qt State Machine standalone documentation

The Qt State Machine was carved off of the qtbase and qtdeclarative repositories
and relocated to the qtscxml repository as a neighbor of the scxml state machine.
As such the Qt State Machine had several fragments of existing documentation, but
no qdoc packaging to make them work as a standalone documentation. This packaging
and related necessary changes is the essence of this commit.

Pick-to: 6.1
Task-number: QTBUG-89833
Change-Id: I43d8f8145d4467bd48dbf4674fa28a29671de868
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

13 files changed, 34 insertions, 51 deletions

diff --git a/examples/statemachine/animation/sub-attaq/qanimationstate.cpp b/examples/statemachine/animation/sub-attaq/qanimationstate.cpp
index 6da0855..99edaf5 100644
--- a/examples/statemachine/animation/sub-attaq/qanimationstate.cpp
+++ b/examples/statemachine/animation/sub-attaq/qanimationstate.cpp
@@ -54,20 +54,15 @@
 
 QT_BEGIN_NAMESPACE
 
-/*!
-\class QAnimationState
+/*
 
-\brief The QAnimationState class provides state that handle an animation and emit
+The QAnimationState class provides state that handle an animation and emit
 a signal when this animation is finished.
 
-\ingroup statemachine
-
 QAnimationState provides a state that handle an animation. It will start this animation
 when the state is entered and stop it when it is leaved. When the animation has finished the
 state emit animationFinished signal.
-QAnimationState is part of \l{The State Machine Framework}.
 
-\code
 QStateMachine machine;
 QAnimationState *s = new QAnimationState(machine->rootState());
 QPropertyAnimation *animation = new QPropertyAnimation(obj, "pos");
@@ -75,28 +70,26 @@ s->setAnimation(animation);
 QState *s2 = new QState(machine->rootState());
 s->addTransition(s, &QAnimationState::animationFinished, s2);
 machine.start();
-\endcode
 
-\sa QState, {The Animation Framework}
 */
 
-/*!
-  Constructs a new state with the given \a parent state.
+/*
+  Constructs a new state with the given parent state.
 */
 QAnimationState::QAnimationState(QState *parent)
     : QState(parent), m_animation(nullptr)
 {
 }
 
-/*!
+/*
   Destroys the animation state.
 */
 QAnimationState::~QAnimationState()
 {
 }
 
-/*!
-  Set an \a animation for this QAnimationState. If an animation was previously handle by this
+/*
+  Set an animation for this QAnimationState. If an animation was previously handle by this
   state then it won't emit animationFinished for the old animation. The QAnimationState doesn't
   take the ownership of the animation.
 */
@@ -117,7 +110,7 @@ void QAnimationState::setAnimation(QAbstractAnimation *animation)
     }
 }
 
-/*!
+/*
   Returns the animation handle by this animation state, or \nullptr if there is no animation.
 */
 QAbstractAnimation* QAnimationState::animation() const
@@ -125,27 +118,18 @@ QAbstractAnimation* QAnimationState::animation() const
     return m_animation;
 }
 
-/*!
-  \reimp
-*/
 void QAnimationState::onEntry(QEvent *)
 {
     if (m_animation)
         m_animation->start();
 }
 
-/*!
-  \reimp
-*/
 void QAnimationState::onExit(QEvent *)
 {
     if (m_animation)
         m_animation->stop();
 }
 
-/*!
-  \reimp
-*/
 bool QAnimationState::event(QEvent *e)
 {
     return QState::event(e);
diff --git a/examples/statemachine/doc/src/animatedtiles.qdoc b/examples/statemachine/doc/src/animatedtiles.qdoc
index 9f1d912..3d1d5d4 100644
--- a/examples/statemachine/doc/src/animatedtiles.qdoc
+++ b/examples/statemachine/doc/src/animatedtiles.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example animation/animatedtiles
     \title Animated Tiles Example
+    \ingroup examples-qtstatemachine
 
     \brief The Animated Tiles example animates items in a graphics scene.
 
diff --git a/examples/statemachine/doc/src/eventtransitions.qdoc b/examples/statemachine/doc/src/eventtransitions.qdoc
index e74831b..72eabfb 100644
--- a/examples/statemachine/doc/src/eventtransitions.qdoc
+++ b/examples/statemachine/doc/src/eventtransitions.qdoc
@@ -28,9 +28,10 @@
 /*!
     \example statemachine/eventtransitions
     \title Event Transitions Example
+    \ingroup examples-qtstatemachine
 
     \brief The Event Transitions example shows how to use event transitions,
-    a feature of \l{The State Machine Framework}.
+    a feature of \l{Qt State Machine Overview}{Qt State Machine Framework}.
 
     The Event Transitions Example illustrates how states change when a
     user enters or leaves the area of a button. The states are handled by
diff --git a/examples/statemachine/doc/src/factorial.qdoc b/examples/statemachine/doc/src/factorial.qdoc
index a0ace96..f332339 100644
--- a/examples/statemachine/doc/src/factorial.qdoc
+++ b/examples/statemachine/doc/src/factorial.qdoc
@@ -28,16 +28,14 @@
 /*!
     \example statemachine/factorial
     \title Factorial States Example
+    \ingroup examples-qtstatemachine
 
-    \brief The Factorial States example shows how to use \l{The State Machine
-    Framework} to calculate the factorial of an integer.
+    \brief The Factorial States example shows how to use \l{Qt State Machine Overview}
+    to calculate the factorial of an integer.
 
     The statechart for calculating the factorial looks as follows:
 
     \image factorial-example.png
-    \omit
-    \caption This is a caption
-    \endomit
 
     In other words, the state machine calculates the factorial of 6 and prints
     the result.
diff --git a/examples/statemachine/doc/src/moveblocks.qdoc b/examples/statemachine/doc/src/moveblocks.qdoc
index 64045f1..e40fd92 100644
--- a/examples/statemachine/doc/src/moveblocks.qdoc
+++ b/examples/statemachine/doc/src/moveblocks.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example animation/moveblocks
     \title Move Blocks Example
+    \ingroup examples-qtstatemachine
 
     \brief The Move Blocks example shows how to animate items in a
     QGraphicsScene using a QStateMachine with a custom transition.
@@ -135,7 +136,7 @@
     \snippet animation/moveblocks/main.cpp 13
 
     As mentioned before, QAbstractTransition will set up an animation
-    added with \l{QAbstractTransition::}{addAnimation()} using
+    added with \l [CPP] {QAbstractTransition::}{addAnimation()} using
     property values set with \l{QState::}{assignProperty()}.
 
     \section1 The StateSwitcher Class
@@ -171,7 +172,7 @@
 
     \c StateSwitchTransition inherits QAbstractTransition and triggers
     on \c{StateSwitchEvent}s. It contains only inline functions, so
-    let's take a look at its \l{QAbstractTransition::}{eventTest()}
+    let's take a look at its \l [CPP] {QAbstractTransition::}{eventTest()}
     function, which is the only function that we define..
 
     \snippet animation/moveblocks/main.cpp 14
diff --git a/examples/statemachine/doc/src/padnavigator.qdoc b/examples/statemachine/doc/src/padnavigator.qdoc
index 31440b6..c286187 100644
--- a/examples/statemachine/doc/src/padnavigator.qdoc
+++ b/examples/statemachine/doc/src/padnavigator.qdoc
@@ -28,11 +28,11 @@
 /*!
     \example graphicsview/padnavigator
     \title Pad Navigator Example
-    \ingroup examples-graphicsview
+    \ingroup examples-qtstatemachine
     \brief Demonstrates how to create animated user interface.
 
     The Pad Navigator Example shows how you can use Graphics View together with
-    embedded widgets and Qt's \l{The State Machine Framework}{state machine
+    embedded widgets and Qt's \l{Qt State Machine Overview}{state machine
     framework} to create a simple but useful, dynamic, animated user interface.
 
     \image padnavigator-example.png
diff --git a/examples/statemachine/doc/src/pingpong.qdoc b/examples/statemachine/doc/src/pingpong.qdoc
index 9545058..8352d49 100644
--- a/examples/statemachine/doc/src/pingpong.qdoc
+++ b/examples/statemachine/doc/src/pingpong.qdoc
@@ -28,17 +28,15 @@
 /*!
     \example statemachine/pingpong
     \title Ping Pong States Example
+    \ingroup examples-qtstatemachine
 
     \brief The Ping Pong States example shows how to use parallel states together
-    with custom events and transitions in \l{The State Machine Framework}.
+    with custom events and transitions in \l{Qt State Machine Overview}{Qt State Machine Framework}.
 
     This example implements a statechart where two states communicate by
     posting events to the state machine. The state chart looks as follows:
 
     \image pingpong-example.png
-    \omit
-    \caption This is a caption
-    \endomit
 
     The \c pinger and \c ponger states are parallel states, i.e. they are
     entered simultaneously and will take transitions independently of
diff --git a/examples/statemachine/doc/src/rogue.qdoc b/examples/statemachine/doc/src/rogue.qdoc
index b8b7cb1..07461ae 100644
--- a/examples/statemachine/doc/src/rogue.qdoc
+++ b/examples/statemachine/doc/src/rogue.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example statemachine/rogue
     \title Rogue Example
+    \ingroup examples-qtstatemachine
 
     \brief The Rogue example shows how to use the Qt state machine for event
     handling.
@@ -142,7 +143,7 @@
     This will enable the rogue to be moved with the keypad.  Notice
     that we don't set a target state for the movement transition. This
     will cause the transition to be triggered (and the
-    \l{QAbstractTransition::}{onTransition()} function to be invoked),
+    \l [CPP] {QAbstractTransition::}{onTransition()} function to be invoked),
     but the machine will not leave the \c inputState. If we had set \c
     inputState as the target state, we would first have left and then
     entered the \c inputState again.
@@ -176,7 +177,7 @@
 
     In the constructor, we tell QEventTransition to only send
     \l{QEvent::}{KeyPress} events to the
-    \l{QAbstractTransition::}{eventTest()} function:
+    \l [CPP] {QAbstractTransition::}{eventTest()} function:
 
     \snippet statemachine/rogue/movementtransition.h 1
 
diff --git a/examples/statemachine/doc/src/states.qdoc b/examples/statemachine/doc/src/states.qdoc
index 1ae379f..30053a9 100644
--- a/examples/statemachine/doc/src/states.qdoc
+++ b/examples/statemachine/doc/src/states.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example animation/states
     \title States Example
+    \ingroup examples-qtstatemachine
 
     \brief The States example shows how to use the Qt state machine to play
     animations.
diff --git a/examples/statemachine/doc/src/stickman.qdoc b/examples/statemachine/doc/src/stickman.qdoc
index ffc7366..4edccc9 100644
--- a/examples/statemachine/doc/src/stickman.qdoc
+++ b/examples/statemachine/doc/src/stickman.qdoc
@@ -28,6 +28,7 @@
 /*!
     \example animation/stickman
     \title Stickman Example
+    \ingroup examples-qtstatemachine
 
     \brief The Stickman example shows how to animate transitions in a state
     machine to implement key frame animations.
diff --git a/examples/statemachine/doc/src/sub-attaq.qdoc b/examples/statemachine/doc/src/sub-attaq.qdoc
index 994e9d6..002b50a 100644
--- a/examples/statemachine/doc/src/sub-attaq.qdoc
+++ b/examples/statemachine/doc/src/sub-attaq.qdoc
@@ -28,10 +28,10 @@
 /*!
     \example animation/sub-attaq
     \title Sub-Attaq
-    \ingroup examples-layout
+    \ingroup examples-qtstatemachine
 
     \brief This example shows Qt's ability to combine \l{The Animation Framework}{the animation framework}
-    and \l{The State Machine Framework}{the state machine framework} to create a game.
+    and \l{Qt State Machine Overview}{the state machine framework} to create a game.
 
     \image sub-attaq-demo.png
 
diff --git a/examples/statemachine/doc/src/trafficlight.qdoc b/examples/statemachine/doc/src/trafficlight.qdoc
index 50c0944..67e87e5 100644
--- a/examples/statemachine/doc/src/trafficlight.qdoc
+++ b/examples/statemachine/doc/src/trafficlight.qdoc
@@ -28,8 +28,9 @@
 /*!
     \example statemachine/trafficlight
     \title Traffic Light Example
+    \ingroup examples-qtstatemachine
 
-    \brief The Traffic Light example shows how to use \l{The State Machine Framework}
+    \brief The Traffic Light example shows how to use \l{Qt State Machine Overview}
     to implement the control flow of a traffic light.
 
     \image trafficlight-example.png
@@ -60,9 +61,6 @@
     LightState to another. Here is the statechart for the light state:
 
     \image trafficlight-example1.png
-    \omit
-    \caption This is a caption
-    \endomit
 
     \snippet statemachine/trafficlight/main.cpp 3
 
@@ -74,9 +72,6 @@
     This is what the statechart looks like:
 
     \image trafficlight-example2.png
-    \omit
-    \caption This is a caption
-    \endomit
 
     \snippet statemachine/trafficlight/main.cpp 4
 
diff --git a/examples/statemachine/doc/src/twowaybutton.qdoc b/examples/statemachine/doc/src/twowaybutton.qdoc
index 2e1c291..6e4eed9 100644
--- a/examples/statemachine/doc/src/twowaybutton.qdoc
+++ b/examples/statemachine/doc/src/twowaybutton.qdoc
@@ -28,9 +28,11 @@
 /*!
     \example statemachine/twowaybutton
     \title Two-way Button Example
+    \ingroup examples-qtstatemachine
 
-    \brief The Two-way button example shows how to use \l{The State Machine
-    Framework} to implement a simple state machine that toggles the current
+    \brief The Two-way button example shows how to use
+    \l{Qt State Machine Overview}{Qt State Machine Framework}
+    to implement a simple state machine that toggles the current
     state when a button is clicked.
 
     \snippet statemachine/twowaybutton/main.cpp 0