Doc: Updated the QML State Machine docs

- Excluded the src/imports/statemachine directory from
qtquick.qdocconf to avoid unnecessary qdoc warnings.
- corrected a broken link to an external source
- changed the group name to avoid collision
- added a \qmlmodule page for QtQml.StateMachine
- Reduced the amount of duplication between the
C++ and QML state machine overviews.

Task-number: QTBUG-41561
Change-Id: I87c815fada7006f0609331e315bb338f062bb4db
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>

1 files changed, 85 insertions, 106 deletions

diff --git a/src/qml/doc/src/statemachine.qdoc b/src/qml/doc/src/statemachine.qdoc
index 5a37ef8026..68c57055ca 100644
--- a/src/qml/doc/src/statemachine.qdoc
+++ b/src/qml/doc/src/statemachine.qdoc
@@ -26,91 +26,77 @@
 ****************************************************************************/
 
 /*!
-  \group qmlstatemachine
+  \qmlmodule QtQml.StateMachine 1.0
+  \title Declarative State Machine QML Types
+  \brief Provides QML types to create and execute state graphs.
+
+  The following is a list of QML types provided by the module:
+*/
+
+
+/*!
   \page qmlstatemachine.html
   \title The Declarative State Machine Framework
-  \brief An overview of the Declarative State Machine Framework for constructing and executing state graphs.
+  \brief Overview of the Declarative State Machine Framework for constructing and executing state graphs.
 
   \ingroup frameworks-technologies
 
   \tableofcontents
 
-  The Declarative State Machine Framework provides classes for creating and executing
-  state graphs in QML. The concepts and notation are based on those from Harel's
-  \l{http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf}
-  {Statecharts: A visual formalism for complex systems}, which
-  is also the basis of UML state diagrams. The semantics of state machine
-  execution are based on \l{State Chart XML: State Machine Notation for
-  Control Abstraction}{State Chart XML (SCXML)}.
-
-  Statecharts provide a graphical way of modeling how a system reacts to
-  stimuli. This is done by defining the possible \e states that the system can
-  be in, and how the system can move from one state to another (\e transitions
-  between states). A key characteristic of event-driven systems (such as Qt
-  applications) is that behavior often depends not only on the last or current
-  event, but also the events that preceded it. With statecharts, this
-  information is easy to express.
-
-  The Declarative State Machine Framework provides an API and execution model that can
-  be used to effectively embed the elements and semantics of statecharts in Qml
-  applications. The framework integrates tightly with Qt's meta-object system;
-  for example, transitions between states can be triggered by signals, and
-  states can be configured to set properties and invoke methods on QObjects.
-  Qt's event system is used to drive the state machines.
-
-  The state graph in the Declarative State Machine Framework is hierarchical. States
-  can be nested inside of other states, and the current configuration of the
-  state machine consists of the set of states which are currently active.
-  All the states in a valid configuration of the state machine will
-  have a common ancestor.
+  The Declarative State Machine Framework provides types for creating and
+  executing state graphs in QML. It is similar to the C++ State Machine
+  framework based on Harel's
+  \l{Statecharts: A visual formalism for complex systems}, which
+  is also the basis for UML state diagrams. Like its
+  \l{The State Machine Framework}{C++ counterpart}, the framework provides an
+  API and execution model based on \l{State Chart XML: State Machine Notation for
+  Control Abstraction}{State Chart XML (SCXML)}
+  to embed the elements and semantics of statecharts in QML applications.
 
   For user interfaces with multiple visual states, independent of the
   application's logical state, consider using QML States and Transitions.
 
-  \section1 QML types in the Declarative State Machine Framework
-
-  These QML types are provided by QML for creating event-driven state machines.
+  These following QML types are provided by framework to create event-driven
+  state machines:
 
-  \annotatedlist qmlstatemachine
+  \annotatedlist statemachine-qmltypes
 
-  \section1 A Simple State Machine
+  \section1 A Simple Example
 
   To demonstrate the core functionality of the State Machine API, let's look
-  at a small example: A state machine with three states, \c s1, \c s2 and \c
-  s3. The state machine is controlled by a single QPushButton; when the button
+  at an example: A state machine with three states, \c s1, \c s2 and \c
+  s3. The state machine is controlled by a single Button; when the button
   is clicked, the machine transitions to another state. Initially, the state
-  machine is in state \c s1. The statechart for this machine is as follows:
+  machine is in state \c s1. The following is a state chart showing the
+  different states in our example.
 
-    \image statemachine-button.png
-    \omit
-    \caption This is a caption
-    \endomit
+  \image statemachine-button.png
 
   The following snippet shows the code needed to create such a state machine.
 
   \snippet qml/statemachine/statemachine-button.qml 0
 
-  The state machine executes asynchronously, i.e. it becomes part of your
-  application's event loop.
+  The state machine runs asynchronously to become part of your application's
+  event loop.
 
   \section1 State Machines That Finish
 
   The state machine defined in the previous section never finishes. In order
   for a state machine to be able to finish, it needs to have a top-level \e
-  final state (FinalState object). When the state machine enters a top-level
-  final state, the machine will emit the \l{StateBase::finished}{finished}
-  signal and halt.
+  final state (FinalState object). When the state machine enters the top-level
+  final state, the machine emits the \l{StateBase::finished}{finished}
+  signal and halts.
 
   All you need to do to introduce a final state in the graph is create a
   FinalState object and use it as the target of one or more transitions.
 
-  \section1 Sharing Transitions By Grouping States
+  \section1 Sharing Transitions
 
   Assume we wanted the user to be able to quit the application at any time by
   clicking a Quit button. In order to achieve this, we need to create a final
   state and make it the target of a transition associated with the Quit
-  button's clicked() signal. We could add a transition from each of \c s1, \c
-  s2 and \c s3; however, this seems redundant, and one would also have to
+  button's \e clicked() signal. We could add a transition for each state;
+  however, this seems redundant and one would also have to
   remember to add such a transition from every new state that is added in the
   future.
 
@@ -121,54 +107,50 @@
   state. The following diagram shows the new state machine.
 
     \image statemachine-button-nested.png
-    \omit
-    \caption This is a caption
-    \endomit
 
   The three original states have been renamed \c s11, \c s12 and \c s13 to
-  reflect that they are now children of the new top-level state, \c s1.  Child
+  reflect that they are now childrens of the new top-level state, \c s1.  Child
   states implicitly inherit the transitions of their parent state. This means
   it is now sufficient to add a single transition from \c s1 to the final
-  state \c s2. New states added to \c s1 will also automatically inherit this
+  state, \c s2. New states added to \c s1 will automatically inherit this
   transition.
 
   All that's needed to group states is to specify the proper parent when the
   state is created. You also need to specify which of the child states is the
-  initial one (i.e. which child state the state machine should enter when the
+  initial one (the child state the state machine should enter when the
   parent state is the target of a transition).
 
   \snippet qml/statemachine/statemachine-button-nested.qml 0
 
   In this case we want the application to quit when the state machine is
-  finished, so the machine's finished() signal is connected to the
-  application's quit() slot.
+  finished, so the machine's \e finished() signal is connected to the
+  application's \e quit() slot.
 
   A child state can override an inherited transition. For example, the
   following code adds a transition that effectively causes the Quit button to
-  be ignored when the state machine is in state \c s12.
+  be ignored when the state machine is in state, \c s12.
 
   \snippet qml/statemachine/statemachine-button-nested-ignore-quit.qml 0
 
-  A transition can have any state as its target, i.e. the target state does
-  not have to be on the same level in the state hierarchy as the source state.
+  A transition can have any state as its target irrespective of where the
+  target state is in the state hierarchy.
 
-  \section1 Using History States to Save and Restore the Current State
+  \section1 Using History States
 
   Imagine that we wanted to add an "interrupt" mechanism to the example
   discussed in the previous section; the user should be able to click a button
   to have the state machine perform some non-related task, after which the
   state machine should resume whatever it was doing before (i.e. return to the
-  old state, which is one of \c s11, \c s12 and \c s13 in this case).
+  old state, which is one of the three states in this case).
 
   Such behavior can easily be modeled using \e{history states}. A history
   state (HistoryState object) is a pseudo-state that represents the child
-  state that the parent state was in the last time the parent state was
-  exited.
+  state that the parent state was in before it exited last.
 
   A history state is created as a child of the state for which we wish to
   record the current child state; when the state machine detects the presence
   of such a state at runtime, it automatically records the current (real)
-  child state when the parent state is exited. A transition to the history
+  child state when the parent state exits. A transition to the history
   state is in fact a transition to the child state that the state machine had
   previously saved; the state machine automatically "forwards" the transition
   to the real child state.
@@ -177,9 +159,6 @@
   has been added.
 
     \image statemachine-button-history.png
-    \omit
-    \caption This is a caption
-    \endomit
 
   The following code shows how it can be implemented; in this example we
   simply display a message box when \c s3 is entered, then immediately return
@@ -187,32 +166,27 @@
 
   \snippet qml/statemachine/statemachine-button-history.qml 0
 
-  \section1 Using Parallel States to Avoid a Combinatorial Explosion of States
+  \section1 Using Parallel States
 
   Assume that you wanted to model a set of mutually exclusive properties of a
   car in a single state machine. Let's say the properties we are interested in
   are Clean vs Dirty, and Moving vs Not moving. It would take four mutually
-  exclusive states and eight transitions to be able to represent and freely
-  move between all possible combinations.
+  exclusive states and eight transitions to represent the states and freely
+  move between all possible combinations as shown in the following state chart.
 
     \image statemachine-nonparallel.png
-    \omit
-    \caption This is a caption
-    \endomit
 
   If we added a third property (say, Red vs Blue), the total number of states
   would double, to eight; and if we added a fourth property (say, Enclosed vs
   Convertible), the total number of states would double again, to 16.
 
-  Using parallel states, the total number of states and transitions grows
-  linearly as we add more properties, instead of exponentially. Furthermore,
-  states can be added to or removed from the parallel state without affecting
-  any of their sibling states.
+  This exponential increase can be reduced using parallel states, which enables
+  linear growth in the number of states and transitions as we add more
+  properties. Furthermore, states can be added to or removed from the parallel
+  state without affecting any of their sibling states. The following state
+  chart shows the different paralles states for the car example.
 
     \image statemachine-parallel.png
-    \omit
-    \caption This is a caption
-    \endomit
 
   To create a parallel state group, set childMode to QState.ParallelStates.
 
@@ -231,19 +205,20 @@
 
   When a parallel state group is entered, all its child states will be
   simultaneously entered. Transitions within the individual child states
-  operate normally. However, any of the child states may take a transition which exits the parent
-  state. When this happens, the parent state and all of its child states are exited.
+  operate normally. However, any of the child states may take a transition
+  which exits the parent state. When this happens, the parent state and all of
+  its child states are exited.
 
-  The parallelism in the State Machine framework follows an interleaved semantics. All parallel
-  operations will be executed in a single, atomic step of the event processing, so no event can
-  interrupt the parallel operations. However, events will still be processed sequentially, since
-  the machine itself is single threaded. As an example: Consider the situation where there are two
-  transitions that exit the same parallel state group, and their conditions become true
-  simultaneously. In this case, the event that is processed last of the two will not have any
-  effect, since the first event will already have caused the machine to exit from the parallel
-  state.
+  The parallelism in the State Machine framework follows an interleaved
+  semantics. All parallel operations will be executed in a single, atomic step
+  of the event processing, so no event can interrupt the parallel operations.
+  However, events will still be processed sequentially, as the machine itself
+  is single threaded. For example, consider the situation where there are two
+  transitions that exit the same parallel state group, and their conditions
+  become true simultaneously. In this case, the event that is processed last
+  of the two will not have any effect.
 
-  \section1 Detecting that a Composite State has Finished
+  \section1 Exiting a Composite State
 
   A child state can be final (a FinalState object); when a final child state
   is entered, the parent state emits the StateBase::finished signal. The
@@ -251,9 +226,6 @@
   before entering a final state:
 
     \image statemachine-finished.png
-    \omit
-    \caption This is a caption
-    \endomit
 
   When \c s1 's final state is entered, \c s1 will automatically emit
   \l{StateBase::finished}{finished}. We use a signal transition to cause this event to
@@ -270,11 +242,11 @@
   \endqml
 
   Using final states in composite states is useful when you want to hide the
-  internal details of a composite state; i.e. the only thing the outside world
-  should be able to do is enter the state, and get a notification when the
-  state has completed its work. This is a very powerful abstraction and
-  encapsulation mechanism when building complex (deeply nested) state
-  machines. (In the above example, you could of course create a transition
+  internal details of a composite state. The outside world should be able to
+  enter the state and get a notification when the state has completed its work,
+  without the need to know the internal details. This is a very powerful
+  abstraction and encapsulation mechanism when building complex (deeply nested)
+  state machines. (In the above example, you could of course create a transition
   directly from \c s1 's \c done state rather than relying on \c s1 's
   finished() signal, but with the consequence that implementation details of
   \c s1 are exposed and depended on).
@@ -286,9 +258,9 @@
 
   A transition need not have a target state. A transition without a target can
   be triggered the same way as any other transition; the difference is that
-  when a targetless transition is triggered, it doesn't cause any state
-  changes. This allows you to react to a signal or event when your machine is
-  in a certain state, without having to leave that state. Example:
+  it doesn't cause any state changes. This allows you to react to a signal or
+  event when your machine is in a certain state, without having to leave that
+  state. For example:
 
   \qml
     Button {
@@ -311,7 +283,14 @@
 
   The "button pressed" message will be displayed each time the button is clicked, but the
   state machine will remain in its current state (s1). If the target state
-  were explicitly set to s1, however, s1 would be exited and re-entered each
-  time (e.g. the QAbstractState::entered and QAbstractState::exited
+  were explicitly set to s1, s1 would be exited and re-entered each
+  time (the QAbstractState::entered and QAbstractState::exited
   signals would be emitted).
+
+  \section1 Related Information
+
+  \list
+   \li \l{Declarative State Machine QML Types}
+   \li \l{The State Machine Framework}
+  \endlist
 */