Added documentation to flow project.

Author: radcortez

batch/flow/pom.xml

@@ -11,8 +11,8 @@
 
     <artifactId>flow</artifactId>
     <packaging>war</packaging>
-
-    <name>${project.artifactId}</name>
+    <name>Batch Flow</name>
+    <description>Batch DSL - Flow</description>
 
     <dependencies>
         <dependency>

batch/flow/src/test/java/org/javaee7/batch/flow/BatchFlowTest.java

@@ -21,10 +21,30 @@
 import static org.junit.Assert.assertEquals;
 
 /**
+ * The Batch specification allows you to implement process workflows using a Job Specification Language (JSL). In this
+ * sample, by using the +flow+ element, we define a sequence of elements that execute together as a unit. When the
+ * flow is finished the flow transitions to the next execution element. The execution elements of a flow cannot
+ * transition to elements outside the flow.
+ *
+ * include::myJob.xml[]
+ *
+ * The flow element is usefull to build self contained workflows that you can reference and build as a part of a bigger
+ * workflow.
+ *
  * @author Roberto Cortez
  */
 @RunWith(Arquillian.class)
 public class BatchFlowTest {
+    /**
+     * We're just going to deploy the application as a +web archive+. Note the inclusion of the following files:
+     *
+     * [source,file]
+     * ----
+     * /META-INF/batch-jobs/myJob.xml
+     * ----
+     *
+     * The +myJob.xml+ file is needed for running the batch definition.
+     */
     @Deployment
     public static WebArchive createDeployment() {
         WebArchive war = ShrinkWrap.create(WebArchive.class)
@@ -36,6 +56,13 @@ public static WebArchive createDeployment() {
         return war;
     }
 
+    /**
+     * In the test, we're just going to invoke the batch execution and wait for completion. To validate the test
+     * expected behaviour we need to query +JobOperator#getStepExecutions+ and the +Metric[]+ object available in the
+     * step execution.
+     *
+     * @throws Exception an exception if the batch could not complete successfully.
+     */
     @Test
     public void testBatchFlow() throws Exception {
         JobOperator jobOperator = BatchRuntime.getJobOperator();
@@ -58,8 +85,11 @@ public void testBatchFlow() throws Exception {
             }
         }
 
+        // <1> Make sure all the steps were executed.
         assertEquals(3, stepExecutions.size());
+        // <2> Make sure all the steps were executed in order of declaration.
         assertArrayEquals(new String[]{"step1", "step2", "step3"}, executedSteps.toArray());
+        // <3> Job should be completed.
         assertEquals(BatchStatus.COMPLETED, jobExecution.getBatchStatus());
     }
 }