Tune samples and update ref docs

- Fix cplayer play logic depending if we pressed
  eject or play.
- Updates to ref docs.

docs/src/reference/asciidoc/introduction.adoc

@@ -1,7 +1,18 @@
 [[introduction]]
 = Introduction
 Spring State Machine(SSM) is a framework for application developers to
-use traditional state machine concepts with Spring applications.
+use traditional state machine concepts with Spring applications. SSM
+aims to provide following features:
+
+* Easy to use flat one level state machine for simple use cases.
+* Hierarchical state machine structure to ease complex state
+  configuration.
+* State machine regions to provide even more complex state
+  configurations.
+* Usage of triggers, transitions, guards and actions.
+* Type safe configuration adapter.
+* State machine event listeners.
+* Spring IOC integration to associate beans with a state machine.
 
 Before you continue it's worth to go through appendices <<glossary>>
 and <<crashcourse>> to get a generic idea of what state machines are

docs/src/reference/asciidoc/sm-examples.adoc

@@ -364,3 +364,68 @@ matched from enums. _@StatesOnTransition_ is then something what user
 can create into his own application to get a type safe annotation where
 a real enums can be used.
 
+Lets see an example how this state machine actually works.
+
+[source,text]
+----
+sm>sm start
+Entry state IDLE
+Entry state CLOSED
+State machine started
+
+sm>cd lcd
+No CD
+
+sm>cd library
+0: Greatest Hits
+  0: Bohemian Rhapsody  05:56
+  1: Another One Bites the Dust  03:36
+1: Greatest Hits II
+  0: A Kind of Magic  04:22
+  1: Under Pressure  04:08
+
+sm>cd eject
+Exit state CLOSED
+Entry state OPEN
+
+sm>cd load 0
+Loading cd Greatest Hits
+
+sm>cd play
+Exit state OPEN
+Entry state CLOSED
+Exit state CLOSED
+Exit state IDLE
+Entry state BUSY
+Entry state PLAYING
+
+sm>cd lcd
+Greatest Hits Bohemian Rhapsody 00:03
+
+sm>cd forward
+
+sm>cd lcd
+Greatest Hits Another One Bites the Dust 00:04
+
+sm>cd stop
+Exit state PLAYING
+Exit state BUSY
+Entry state IDLE
+Entry state CLOSED
+
+sm>cd lcd
+Greatest Hits
+----
+
+What happened in above run:
+
+* State machine is started which causes machine to get initialized.
+* CD Player lcd screen status is printed.
+* CD Library is printed.
+* CD Player deck is opened.
+* CD with index 0 is loaded into a deck.
+* Play is causing deck to get closed and immediate playing because cd
+  was inserted.
+* We print lcd status and request next track.
+* We stop playing.
+

docs/src/reference/asciidoc/sm.adoc

@@ -117,6 +117,35 @@ specifially handle a case that same bean will be called by a different
 state machines. This limitation is something which will be resolved in
 future releases.
 
+[[sm-triggers]]
+== Triggering Transitions
+Driving a statemachine is done via transitions which are triggerred
+by triggers. Currently supported triggers are _EventTrigger_ and
+_TimerTrigger_.
+
+=== EventTrigger
+_EventTrigger_ is the most useful trigger because it allows user to
+directly interact with a state machine by sending events to it. These
+events are also called signals. Trigger is added to a transition simply
+by associating a state to it during a configuration.
+
+[source,java,indent=0]
+----
+include::samples/DocsConfigurationSampleTests.java[tags=snippetO]
+----
+In above example we send an event using two different ways. Firstly we
+simply sent a type safe event using state machine api method
+`sendEvent(E event)`. Secondly we send event wrapped in a Spring
+messaging _Message_ using api method `sendEvent(Message<E> message)`
+with a custom event headers. This allows user to add arbitrary extra
+information with an event which is then visible to _StateContext_ when
+for example user is implementing actions.
+
+=== TimerTrigger
+_TimerTrigger_ is useful when something needs to be triggered
+automatically without any user interaction. Trigger is added to a
+transition by associating a timer to it during a configuration.
+
 [[sm-listeners]]
 == Listening State Machine Events
 There are use cases where you just want to know what is happening with

spring-statemachine-samples/cdplayer/src/main/java/demo/cdplayer/Application.java

@@ -196,6 +196,7 @@ public class Application  {
 		@Override
 		public void execute(StateContext<States, Events> context) {
 			if (context.getTransition() != null
+					&& context.getEvent() == Events.PLAY
 					&& context.getTransition().getTarget().getId() == States.CLOSED
 					&& context.getExtendedState().getVariables().get(Variables.CD) != null) {
 				context.getStateMachine().sendEvent(Events.PLAY);

spring-statemachine-samples/cdplayer/src/main/java/demo/cdplayer/CdPlayer.java

@@ -91,7 +91,7 @@ public class CdPlayer {
 	}
 
 //tag::snippetB[]
-	@StatesOnTransition(target = States.CLOSED)
+	@StatesOnTransition(target = {States.CLOSED, States.IDLE})
 	public void closed(ExtendedState extendedState) {
 		Object cd = extendedState.getVariables().get(Variables.CD);
 		if (cd != null) {