Update documentation for release

.travis.yml

@@ -17,7 +17,7 @@ after_success:
 - git push -q origin gh-pages
 env:
   global:
-  - JARSPEC_VERSION=1.1.0-SNAPSHOT
+  - JARSPEC_VERSION=2.0.0-SNAPSHOT
   - secure: M3NfQJJ4eAo6iLNH1+/fpOnPnb5LwnrvPfxsb8KeP9Cn5I6p0Ga3uBsHYgxEZu/DygocDNLdzZJ5WF3Z49wtHXPdnWB5Ui1s42sbXczLhGVDKu6VOo8Z0oMLTKSiRwb1LOMxOVCBa1FZo+Zv5HGFTJCyPs3B7w9Lla7S+13KCLw=
   - secure: Umn7Lgz/h/6WW0Q0CMPCjEIDGcqARE6/GvN9/CFx576F/nICzWxhKicfyWUmEf2LXZ43/7qCyC58m0zP4q7gzUteCCSu/TL1YMuhu7DYwm535eTiKWDUpVJo0+dqdqU4e/97lcetqwL93LJNKmEUOwI3BVhp+5DCxZFLOGvZb8Y=
   - secure: b+r3RPUvcyGJaLfl6MIbkM/bpdua1UOXcpB4eAdvR8J5P53BMST7hRbKQQoozS6BNxKoWsBLM6TE2pgLb/BFekehTXjA6Jfr1xOUa2A+6IHqJi9EPFrT7nYxwDwvqsjtYDnApzkv6oGhzYi1Yl2yaLAyEBM5Wx3LX/E1Y5jd0lQ=

README.md

@@ -1,4 +1,4 @@
-# ![JarSpec](http://hgc.io/jarspec/1.1.0-SNAPSHOT/images/logo.svg)
+# ![JarSpec](http://hgc.io/jarspec/2.0.0-SNAPSHOT/images/logo.svg)
 
 ## What?
 [RSpec](http://rspec.info/) (or [Jasmine](http://jasmine.github.io/2.0/introduction.html)/[Mocha](http://visionmedia.github.io/mocha/)) style tests for native Java 8, a bit like the following:
@@ -21,7 +21,7 @@ Allows for more expressive test names without very_long_underscore_ridden_test_m
 
 ## How?
 
-1. Add JarSpec to your project dependencies. See below for Maven and [the dependency info page](http://hgc.io/jarspec/1.0.0/dependency-info.html) for other build tools.
+1. Add JarSpec to your project dependencies. See below for Maven and [the dependency info page](http://hgc.io/jarspec/2.0.0-SNAPSHOT/dependency-info.html) for other build tools.
 
 2. Start writing specs! See [wiki/Implementing Specifications](https://github.com/hgcummings/jarspec/wiki/Implementing-Specifications) for more details, or the [project's own tests](https://github.com/hgcummings/jarspec/tree/master/src/test/java/io/hgc/jarspec) for examples.
 
@@ -35,7 +35,7 @@ Add the dependency to your pom:
         <dependency>
             <groupId>io.hgc</groupId>
             <artifactId>jarspec</artifactId>
-            <version>1.0.0</version>
+            <version>2.0.0</version>
             <scope>test</scope>
         </dependency>
         ....
@@ -65,7 +65,7 @@ Configure SureFire to pick up classes named `*Spec` (although you can stick with
 
 ## When?
 
-The current release on Maven Central is stable and already supports most use cases. See [open milestones](https://github.com/hgcummings/jarspec/issues/milestones) for further planned features. Previous releases have maintained backwards compatibility and upcoming releases are expected to do so as well.
+The current release on Maven Central is stable. See [open milestones](https://github.com/hgcummings/jarspec/milestones) for further planned features. Releases numbers follow the [Semantic Versioning](http://semver.org/) specification for backwards compatibility.
 
 ---
-###### Developer resources: [Test results](http://hgc.io/jarspec/1.1.0-SNAPSHOT/surefire-report.html) [![Build status](https://travis-ci.org/hgcummings/jarspec.svg?branch=master)](https://travis-ci.org/hgcummings/jarspec) [Coverage report](http://hgc.io/jarspec/1.1.0-SNAPSHOT/jacoco/index.html) [![Coverage Status](https://coveralls.io/repos/hgcummings/jarspec/badge.png?branch=master)](https://coveralls.io/r/hgcummings/jarspec?branch=master) [Task board](https://huboard.com/hgcummings/jarspec)
+###### Developer resources: [Test results](http://hgc.io/jarspec/2.0.0-SNAPSHOT/surefire-report.html) [![Build status](https://travis-ci.org/hgcummings/jarspec.svg?branch=master)](https://travis-ci.org/hgcummings/jarspec) [Coverage report](http://hgc.io/jarspec/2.0.0-SNAPSHOT/jacoco/index.html) [![Coverage Status](https://coveralls.io/repos/hgcummings/jarspec/badge.png?branch=master)](https://coveralls.io/r/hgcummings/jarspec?branch=master) [Task board](https://huboard.com/hgcummings/jarspec)

pom.xml

@@ -6,7 +6,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>io.hgc</groupId>
     <artifactId>jarspec</artifactId>
-    <version>1.1.0-SNAPSHOT</version>
+    <version>2.0.0-SNAPSHOT</version>
     <name>${project.groupId}:${project.artifactId}</name>
     <description>RSpec/Jasmine style tests for native Java 8</description>
     <url>https://github.com/hgcummings/jarspec</url>
@@ -186,7 +186,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-report-plugin</artifactId>
-                <version>2.17</version>
+                <version>2.20</version>
                 <configuration>
                     <linkXRef>false</linkXRef>
                 </configuration>

src/main/java/io/hgc/jarspec/Specification.java

@@ -9,8 +9,13 @@
 public interface Specification {
     SpecificationNode root();
 
-    default SpecificationNode describe(String unit, SpecificationNode... specificationNodes) {
-        return SpecificationNode.internal(unit, Stream.of(specificationNodes));
+    /**
+     * @param unit description of a unit of behaviour
+     * @param specifications nested specifications for the behaviour of the unit
+     * @return the overall specification
+     */
+    default SpecificationNode describe(String unit, SpecificationNode... specifications) {
+        return SpecificationNode.internal(unit, Stream.of(specifications));
     }
 
     /**

src/main/java/io/hgc/jarspec/SpecificationNode.java

@@ -33,8 +33,20 @@ public SpecificationNode skip() {
      */
     public abstract SpecificationNode only();
 
+    /**
+     * Add a rule to be applied to all descendant tests of this node.
+     *
+     * @param rule a JUnit TestRule to apply to tests under this node.
+     * @return a new node representing the original node with the rule applied to all of its tests
+     */
     public abstract SpecificationNode withRule(TestRule rule);
 
+    /**
+     * Add a rule to be applied to this node itself (not its descendant tests)
+     *
+     * @param rule a JUnit TestRule to apply to this node
+     * @return a new node representing the original node with the rule applied to it
+     */
     public abstract SpecificationNode withBlockRule(TestRule rule);
 
     abstract String description();

src/test/java/io/hgc/jarspec/examples/JarSpecSpec.java

@@ -26,28 +26,8 @@ public SpecificationNode root() {
                         it("has another nested statement", () ->
                             System.out.println("    Second nested statement execution"))
                     );
-                }).withRule(new ExternalResource() {
-                    @Override
-                    protected void before() throws Throwable {
-                        System.out.println("  inner ExternalResource setup");
-                    }
-
-                    @Override
-                    protected void after() {
-                        System.out.println("  inner ExternalResource teardown");
-                    }
                 })
             );
-        }).withRule(new ExternalResource() {
-            @Override
-            protected void before() throws Throwable {
-                System.out.println("  outer ExternalResource setup");
-            }
-
-            @Override
-            protected void after() {
-                System.out.println("  outer ExternalResource teardown");
-            }
         });
     }
 }

src/test/java/io/hgc/jarspec/examples/RulesSpec.java

@@ -0,0 +1,52 @@
+package io.hgc.jarspec.examples;
+
+import io.hgc.jarspec.JarSpecJUnitRunner;
+import io.hgc.jarspec.Specification;
+import io.hgc.jarspec.SpecificationNode;
+import org.junit.rules.ExternalResource;
+import org.junit.rules.TestRule;
+import org.junit.runner.RunWith;
+
+@RunWith(JarSpecJUnitRunner.class)
+public class RulesSpec implements Specification {
+    @Override
+    public SpecificationNode root() {
+        return describe("major unit",
+            it("has a top-level statement", () ->
+                System.out.println("  Top-level statement execution")),
+            describe("nested minor unit",
+                it("has a nested statement", () ->
+                    System.out.println("    First nested statement execution")
+                ).withRule(log("    Individual test rule")),
+                it("has another nested statement",
+                    () -> System.out.println("    Second nested statement execution"))
+            ).withRule(log("  First nested rule"))
+            .withRule(log("  Second nested rule"))
+            .withBlockRule(log("  Nested block rule"))
+        ).withRule(log("First top-level rule"))
+        .withRule(log("Second top-level rule"))
+        .withBlockRule(log("Top-level block rule"));
+    }
+
+    private static TestRule log(String name) {
+        return new LoggingRule(name);
+    }
+
+    private static class LoggingRule extends ExternalResource {
+        private final String name;
+
+        private LoggingRule(String name) {
+            this.name = name;
+        }
+
+        @Override
+        public void before() {
+            System.out.println(name + " before()");
+        }
+
+        @Override
+        public void after() {
+            System.out.println(name + " after()");
+        }
+    }
+}