Docs changes

- Relates #742

docs/src/reference/asciidoc/appendix-reactormigration-communicating.adoc

@@ -11,7 +11,8 @@ include::samples/DocsMigrationTests.java[tags=snippetA]
 
 We're now solely working on a spring `Message` and reactor `Mono` and `Flux` classes.
 You can send a `Mono` of a `Message` and receive back a `Flux` of `StateMachineEventResult`.
-Remember that nothing happens until you subscribe to this `Flux`.
+Remember that nothing happens until you subscribe to this `Flux`. More about
+this returned value, see <<sm-triggers-statemachineeventresult>>.
 
 ====
 [source,java,indent=0]
@@ -38,3 +39,13 @@ do something when event handling is completed, you could do something like.
 include::samples/DocsMigrationTests.java[tags=snippetB3]
 ----
 ====
+
+Old API methods returning a `boolean` for accepted status are still in place
+but are deprecated to get removed in future releases.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsMigrationTests.java[tags=snippetB4]
+----
+====

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

@@ -20,13 +20,13 @@ include::samples/DocsConfigurationSampleTests.java[tags=snippetO]
 ----
 ====
 
-The preceding example sends an event two different ways. First, it
-sends a type-safe event by using the state machine API method called
-`sendEvent(E event)`. Second, it sends an event wrapped in a Spring
-messaging `Message` by using the API method called `sendEvent(Message<E> message)`
-with a custom event headers. This lets us add arbitrary extra
-information to an event, which is then visible to `StateContext` when
-(for example) you implement actions.
+IMPORTANT: Nothing happens until returned flux is subscribed. See more about it from
+<<sm-triggers-statemachineeventresult>>.
+
+The preceding example sends an events by constructing a `Mono` wrapping
+a `Message` and subscribing into returned `Flux` of results. `Message` lets
+us add arbitrary extra information to an event, which is then visible
+to `StateContext` when (for example) you implement actions.
 
 NOTE: Message headers are generally passed on until machine runs to
 completion for a specific event. For example if an event is causing
@@ -34,6 +34,25 @@ transition into a state `A` which have an anonymous transition into a
 state `B`, original event is available for actions or guards in state
 `B`.
 
+It is also possible to send a `Flux` of messages instead of sending just
+one with a `Mono`.
+
+====
+[source,java,indent=0]
+----
+include::samples/DocsConfigurationSampleTests.java[tags=snippetO2]
+----
+====
+
+[[sm-triggers-statemachineeventresult]]
+==== StateMachineEventResult
+
+`StateMachineEventResult` contains more detailed information about a result
+of a event sending. From this you can get a `Region` which handled an event,
+`Message` itself and what was an actual `ResultType`. From `ResultType` you
+can see if message was accepted, denied or deferred. Generally speaking when
+subscribtion completes, events are passed into a machine.
+
 === Using `TimerTrigger`
 
 `TimerTrigger` is useful when something needs to be triggered

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java

@@ -32,6 +32,7 @@ import org.springframework.messaging.support.MessageBuilder;
 import org.springframework.statemachine.AbstractStateMachineTests;
 import org.springframework.statemachine.StateContext;
 import org.springframework.statemachine.StateMachine;
+import org.springframework.statemachine.StateMachineEventResult;
 import org.springframework.statemachine.access.StateMachineAccess;
 import org.springframework.statemachine.action.Action;
 import org.springframework.statemachine.action.Actions;
@@ -62,6 +63,7 @@ import org.springframework.statemachine.support.StateMachineInterceptorAdapter;
 import org.springframework.statemachine.transition.Transition;
 import org.springframework.statemachine.transition.TransitionConflictPolicy;
 
+import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
 /**
@@ -584,22 +586,39 @@ public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
 
 // tag::snippetO[]
 		@Autowired
-		StateMachine<States, Events> stateMachine;
+		StateMachine<String, String> stateMachine;
 
 		void signalMachine() {
 			stateMachine
 				.sendEvent(Mono.just(MessageBuilder
-					.withPayload(Events.E1).build()))
+					.withPayload("E1").build()))
 				.subscribe();
 
-			Message<Events> message = MessageBuilder
-					.withPayload(Events.E2)
+			Message<String> message = MessageBuilder
+					.withPayload("E2")
 					.setHeader("foo", "bar")
 					.build();
 			stateMachine.sendEvent(Mono.just(message)).subscribe();
 		}
 // end::snippetO[]
 
+		void signalMachine2() {
+// tag::snippetO2[]
+			Message<String> message1 = MessageBuilder
+				.withPayload("E1")
+				.build();
+			Message<String> message2 = MessageBuilder
+				.withPayload("E2")
+				.build();
+
+			Flux<StateMachineEventResult<String, String>> results =
+				stateMachine.sendEvents(Flux.just(message1, message2));
+
+			results.subscribe();
+
+// end::snippetO2[]
+		}
+
 	}
 
 // tag::snippetP[]

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsMigrationTests.java

@@ -23,6 +23,7 @@ import org.springframework.statemachine.StateMachineEventResult;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 
+@SuppressWarnings({ "unused", "deprecation" })
 public class DocsMigrationTests {
 
 	StateMachine<String, String> machine;
@@ -55,4 +56,10 @@ public class DocsMigrationTests {
 			.subscribe();
 		// end::snippetB3[]
 	}
+
+	public void sample3() {
+		// tag::snippetB4[]
+		boolean accepted = machine.sendEvent("EVENT");
+		// end::snippetB4[]
+	}
 }