doc improvements

4 files changed, 51 insertions, 23 deletions

diff --git a/src/corelib/statemachine/qfinalstate.cpp b/src/corelib/statemachine/qfinalstate.cpp
index 772ec87..0980336 100644
--- a/src/corelib/statemachine/qfinalstate.cpp
+++ b/src/corelib/statemachine/qfinalstate.cpp
@@ -55,9 +55,9 @@ QT_BEGIN_NAMESPACE
   A final state is used to communicate that (part of) a QStateMachine has
   finished its work. When a final top-level state is entered, the state
   machine's \l{QStateMachine::finished()}{finished}() signal is emitted. In
-  general, when a final substate (a child of a QState) is entered, a
-  QStateFinishedEvent is generated for the final state's parent
-  state. QFinalState is part of \l{The State Machine Framework}.
+  general, when a final substate (a child of a QState) is entered, the parent
+  state's \l{QState::finished()}{finished}() signal is emitted.  QFinalState
+  is part of \l{The State Machine Framework}.
 
   To use a final state, you create a QFinalState object and add a transition
   to it from another state. Example:
@@ -76,6 +76,8 @@ QT_BEGIN_NAMESPACE
   machine.setInitialState(s1);
   machine.start();
   \endcode
+
+  \sa QStateMachine::finished(), QState::finished()
 */
 
 class QFinalStatePrivate : public QAbstractStatePrivate
diff --git a/src/corelib/statemachine/qhistorystate.cpp b/src/corelib/statemachine/qhistorystate.cpp
index b6ec471..d1b2391 100644
--- a/src/corelib/statemachine/qhistorystate.cpp
+++ b/src/corelib/statemachine/qhistorystate.cpp
@@ -58,9 +58,8 @@ QT_BEGIN_NAMESPACE
   other child states of the parent state. QHistoryState is part of \l{The
   State Machine Framework}.
 
-  Use QState::addHistoryState() to construct a history state. Use the
-  setDefaultState() function to set the state that should be entered if the
-  parent state has never been entered.  Example:
+  Use the setDefaultState() function to set the state that should be entered
+  if the parent state has never been entered.  Example:
 
   \code
   QStateMachine machine;
@@ -69,7 +68,7 @@ QT_BEGIN_NAMESPACE
   QState *s11 = new QState(s1);
   QState *s12 = new QState(s1);
 
-  QState *s1h = s1->addHistoryState();
+  QHistoryState *s1h = new QHistoryState(s1);
   s1h->setDefaultState(s11);
 
   machine.addState(s1);
@@ -83,6 +82,9 @@ QT_BEGIN_NAMESPACE
   // state if s1 has never been entered.
   s1->addTransition(button, SIGNAL(clicked()), s1h);
   \endcode
+
+  By default a history state is shallow, meaning that it won't remember nested
+  states. This can be configured through the historyType property.
 */
 
 /*!
@@ -95,6 +97,8 @@ QT_BEGIN_NAMESPACE
   \property QHistoryState::historyType
 
   \brief the type of history that this history state records
+
+  The default value of this property is QHistoryState::ShallowHistory.
 */
 
 /*!
diff --git a/src/corelib/statemachine/qstate.cpp b/src/corelib/statemachine/qstate.cpp
index 3220619..4c9e033 100644
--- a/src/corelib/statemachine/qstate.cpp
+++ b/src/corelib/statemachine/qstate.cpp
@@ -68,22 +68,30 @@ QT_BEGIN_NAMESPACE
   The assignProperty() function is used for defining property assignments that
   should be performed when a state is entered.
 
+  Top-level states must be passed QStateMachine::rootState() as their parent
+  state, or added to a state machine using QStateMachine::addState().
+
   \section1 States with Child States
 
-  For non-parallel state groups, the setInitialState() function must be called
-  to set the initial state. The child states are mutually exclusive states,
-  and the state machine needs to know which child state to enter when the
-  parent state is the target of a transition.
+  The childMode property determines how child states are treated. For
+  non-parallel state groups, the setInitialState() function must be called to
+  set the initial state. The child states are mutually exclusive states, and
+  the state machine needs to know which child state to enter when the parent
+  state is the target of a transition.
+
+  The state emits the QState::finished() signal when a final child state
+  (QFinalState) is entered.
 
   The setErrorState() sets the state's error state. The error state is the
   state that the state machine will transition to if an error is detected when
   attempting to enter the state (e.g. because no initial state has been set).
+
 */
 
 /*!
     \property QState::initialState
 
-    \brief the initial state of this state
+    \brief the initial state of this state (one of its child states)
 */
 
 /*!
@@ -96,6 +104,8 @@ QT_BEGIN_NAMESPACE
     \property QState::childMode
 
     \brief the child mode of this state
+
+    The default value of this property is QState::ExclusiveStates.
 */
 
 /*!
@@ -456,6 +466,8 @@ bool QState::event(QEvent *e)
   \fn QState::finished()
 
   This signal is emitted when a final child state of this state is entered.
+
+  \sa QFinalState
 */
 
 /*!
diff --git a/src/corelib/statemachine/qstatemachine.cpp b/src/corelib/statemachine/qstatemachine.cpp
index 232d801..6f626f5 100644
--- a/src/corelib/statemachine/qstatemachine.cpp
+++ b/src/corelib/statemachine/qstatemachine.cpp
@@ -163,6 +163,8 @@ QT_BEGIN_NAMESPACE
     \property QStateMachine::initialState
 
     \brief the initial state of this state machine
+
+    The initial state must be one of the rootState()'s child states.
 */
 
 /*!
@@ -181,6 +183,9 @@ QT_BEGIN_NAMESPACE
     \property QStateMachine::globalRestorePolicy
 
     \brief the restore policy for states of this state machine.
+
+    The default value of this property is
+    QStateMachine::DoNotRestoreProperties.
 */
 
 #ifndef QT_NO_ANIMATION
@@ -188,6 +193,10 @@ QT_BEGIN_NAMESPACE
     \property QStateMachine::animationsEnabled
 
     \brief whether animations are enabled
+
+    The default value of this property is true.
+
+    \sa QAbstractTransition::addAnimation()
 */
 #endif
 
@@ -1663,7 +1672,7 @@ void QStateMachine::setInitialState(QAbstractState *state)
   If the state is already in a different machine, it will first be removed
   from its old machine, and then added to this machine.
 
-  \sa removeState(), rootState()
+  \sa removeState(), rootState(), setInitialState()
 */
 void QStateMachine::addState(QAbstractState *state)
 {
@@ -1700,10 +1709,9 @@ void QStateMachine::removeState(QAbstractState *state)
 }
 
 /*!
-  Starts this state machine.
-  The machine will reset its configuration and transition to the initial
-  state.  When a final top-level state is entered, the machine will emit the
-  finished() signal.
+  Starts this state machine.  The machine will reset its configuration and
+  transition to the initial state.  When a final top-level state (QFinalState)
+  is entered, the machine will emit the finished() signal.
 
   \sa started(), finished(), stop(), initialState()
 */
@@ -1730,9 +1738,10 @@ void QStateMachine::start()
 }
 
 /*!
-  Stops this state machine.
+  Stops this state machine. The state machine will stop processing events and
+  then emit the stopped() signal.
 
-  \sa stopped()
+  \sa stopped(), start()
 */
 void QStateMachine::stop()
 {
@@ -1813,7 +1822,8 @@ QSet<QAbstractState*> QStateMachine::configuration() const
 /*!
   \fn QStateMachine::started()
 
-  This signal is emitted when the state machine has entered its initial state.
+  This signal is emitted when the state machine has entered its initial state
+  (QStateMachine::initialState).
 
   \sa QStateMachine::finished(), QStateMachine::start()
 */
@@ -1822,7 +1832,7 @@ QSet<QAbstractState*> QStateMachine::configuration() const
   \fn QStateMachine::finished()
 
   This signal is emitted when the state machine has reached a top-level final
-  state.
+  state (QFinalState).
 
   \sa QStateMachine::started()
 */
@@ -1832,7 +1842,7 @@ QSet<QAbstractState*> QStateMachine::configuration() const
 
   This signal is emitted when the state machine has stopped.
 
-  \sa QStateMachine::stop()
+  \sa QStateMachine::stop(), QStateMachine::finished()
 */
 
 /*!
@@ -2110,7 +2120,7 @@ QSignalEvent::~QSignalEvent()
 
   Returns the index of the signal.
 
-  \sa QMetaObject::indexOfSignal()
+  \sa QMetaObject::indexOfSignal(), QMetaObject::method()
 */
 
 /*!