Add readme to cucumber-junit

Author: mpkorstanje

junit/README.md

@@ -0,0 +1,54 @@
+Cucumber JUnit 
+==============
+
+Use JUnit to execute cucumber scenarios.
+
+Add the `cucumber-junit` dependency to your pom.
+
+```xml
+<dependencies>
+  [...]
+    <dependency>
+        <groupId>io.cucumber</groupId>
+        <artifactId>cucumber-junit</artifactId>
+        <version>${cucumber.version}</version>
+        <scope>test</scope>
+    </dependency>
+  [...]
+</dependencies>
+```
+
+Create an empty class that uses the Cucumber JUnit runner.
+
+```java
+package com.example;
+
+import cucumber.api.CucumberOptions;
+import cucumber.api.junit.Cucumber;
+import org.junit.runner.RunWith;
+
+@RunWith(Cucumber.class)
+@CucumberOptions(plugin = "json:target/cucumber-report.json")
+public class RunCukesTest {
+}
+```
+
+This will execute all scenarios in same package as the runner, by default glue code is also assumed to be in the same 
+package. The `@CucumberOptions` can be used to provide
+[additional configuration](https://cucumber.io/docs/reference/jvm#list-configuration-options) to the runner. 
+
+
+## Using JUnit Rules ##
+
+Cucumber supports JUnits `@ClassRule`, `@BeforeClass` and `@AfterClass` annotations. These will executed before and 
+after all features. Using these is not recommended as it limits the portability between different runners; they may not
+execute correctly when using the commandline, [IntelliJ IDEA](https://www.jetbrains.com/help/idea/cucumber.html) or
+[Cucumber-Eclipse](https://github.com/cucumber/cucumber-eclipse). Instead it is recommended to use Cucumbers `Before` 
+and `After` hooks.
+
+## Using other JUnit features ##
+
+The Cucumber runner acts like a suite of a JUnit tests. As such other JUnit features such as Categories, Custom JUnit 
+Listeners and Reporters can all be expected to work.
+
+For more information on JUnit, see the [JUnit web site](http://www.junit.org).

junit/src/main/java/cucumber/api/junit/Cucumber.java

@@ -33,12 +33,12 @@
  * Classes annotated with {@code @RunWith(Cucumber.class)} will run a Cucumber Feature.
  * In general, the runner class should be empty without any fields or methods.
  * For example:
- *
+ * <p>
  * <blockquote><pre>
  * &#64;RunWith(Cucumber.class)
  * &#64;CucumberOptions(plugin = "pretty")
  * public class RunCukesTest {
- *
+ * <p>
  * }
  * </pre></blockquote>
  * <p>
@@ -48,7 +48,9 @@
  * Additional hints can be given to Cucumber by annotating the class with {@link CucumberOptions}.
  * <p>
  * Cucumber also supports JUnits {@link ClassRule}, {@link BeforeClass} and {@link AfterClass} annotations.
- * These will be invoked around the suite of features" and moved to the end of the java doc.
+ * These will be invoked around the suite of features.  Using these is not recommended as it limits the portability
+ * between different runners; they may not execute correctly when using the commandline, IntelliJ IDEA or
+ * Cucumber-Eclipse. Instead it is recommended to use Cucumbers `Before` and `After` hooks.
  *
  * @see CucumberOptions
  */