Improved documentation

json-assert/src/main/java/com/jayway/jsonassert/impl/JSONAsserter.java

@@ -17,34 +17,93 @@ public class JSONAsserter {
 
     private final JSONReader reader;
 
+    /**
+     * Creates a new instance of a JSONAsserter that can be used to make
+     * assertions on the provided JSON document or array.
+     *
+     * @param json the JSON document to create a JSONAsserter for
+     * @return a JSON asserter initialized with the provided document
+     * @throws ParseException
+     */
     public static JSONAsserter with(String json) throws ParseException {
         return new JSONAsserter(JSONReader.parse(json));
     }
 
+    /**
+     * Instantiates a new JSONAsserter
+     *
+     * @param reader initialized with the JSON document to be asserted upon
+     */
     private JSONAsserter(JSONReader reader) {
         this.reader = reader;
     }
 
+    /**
+     * Asserts that object specified by path satisfies the condition specified by matcher.
+     * If not, an AssertionError is thrown with information about the matcher
+     * and failing value. Example:
+     * <p/>
+     * <code>
+     * with(json).assertThat("items[0].name", equalTo("Bobby"))
+     *           .assertThat("items[0].age" , equalTo(24L))
+     * </code>
+     *
+     * @param path    the json path specifying the value being compared
+     * @param matcher an expression, built of Matchers, specifying allowed values
+     * @param <T>     the static type accepted by the matcher
+     * @return this to allow fluent assertion chains
+     */
     public <T> JSONAsserter assertThat(String path, Matcher<T> matcher) {
-
         MatcherAssert.assertThat((T) reader.get(path), matcher);
-
         return this;
     }
 
+    /**
+     * Asserts that object specified by path is equal to the expected value.
+     * If they are not, an AssertionError is thrown with the given message.
+     *
+     * @param path     the json path specifying the value being compared
+     * @param expected the expected value
+     * @param <T>      the static type that should be returned by the path
+     * @return this to allow fluent assertion chains
+     */
     public <T> JSONAsserter assertEquals(String path, T expected) {
         return assertThat(path, equalTo(expected));
     }
 
-    public <T> JSONAsserter assertNull(String path) {
+    /**
+     * Asserts that object specified by path is null. If it is not, an AssertionError
+     * is thrown with the given message.
+     *
+     * @param path the json path specifying the value that should be null
+     * @return this to allow fluent assertion chains
+     */
+    public JSONAsserter assertNull(String path) {
         return assertThat(path, nullValue());
     }
 
+    /**
+     * Asserts that object specified by path is NOT null. If it is, an AssertionError
+     * is thrown with the given message.
+     *
+     * @param path the json path specifying the value that should be NOT null
+     * @return this to allow fluent assertion chains
+     */
     public <T> JSONAsserter assertNotNull(String path) {
         return assertThat(path, notNullValue());
     }
 
-    public JSONAsserter and(){
+    /**
+     * Syntactic sugar to allow chaining assertions with a separating and() statement
+     * <p/>
+     * <p/>
+     * <code>
+     * with(json).assertThat("firstName", is(equalTo("Bobby"))).and().assertThat("lastName", is(equalTo("Ewing")))
+     * </code>
+     *
+     * @return this to allow fluent assertion chains
+     */
+    public JSONAsserter and() {
         return this;
     }
 

json-assert/src/main/java/com/jayway/jsonassert/impl/JSONReader.java

@@ -63,7 +63,7 @@ public class JSONReader {
         return getByPath(Boolean.class, path);
     }
 
-    public List getList(String path) {
+    public <T> List<T> getList(String path) {
         return getByPath(List.class, path);
     }
 

json-assert/src/test/java/com/jayway/jsonassert/JSONAsserterTest.java

@@ -21,6 +21,18 @@ public class JSONAsserterTest {
         JSONAsserter.with(TEST_DOCUMENT).assertThat("stringField", equalTo("string-field"));
     }
 
+    @Test
+    public void array_content_can_be_asserted_with_matcher() throws Exception {
+
+        JSONAsserter.with(TEST_DOCUMENT).assertThat("stringList", hasItems("ONE", "TWO"));
+    }
+
+    @Test
+    public void map_content_can_be_asserted_with_matcher() throws Exception {
+
+        JSONAsserter.with(TEST_DOCUMENT).assertThat("subDocument", hasEntry("subField", "sub-field"));
+    }
+
     @Test
     public void a_path_can_be_asserted_equal_to() throws Exception {
 
@@ -54,6 +66,4 @@ public class JSONAsserterTest {
     }
 
 
-
-
 }

json-assert/src/test/java/com/jayway/jsonassert/JSONReaderTest.java

@@ -4,6 +4,7 @@ import com.jayway.jsonassert.impl.JSONReader;
 import org.junit.Test;
 
 import java.text.ParseException;
+import java.util.List;
 
 import static org.junit.Assert.*;
 
@@ -87,7 +88,9 @@ public class JSONReaderTest {
     public void a_list_can_be_accessed_in_a_document() throws Exception {
         JSONReader reader = JSONReader.parse(TEST_DOCUMENT);
 
-        assertEquals(2, reader.getList("stringList").size());
+        List<String> l = reader.<String>getList("stringList");
+
+        assertEquals(2, l.size());
     }
 
     @Test
@@ -189,7 +192,9 @@ public class JSONReaderTest {
     public void array_wildcard_property_extract() throws Exception {
         JSONReader reader = JSONReader.parse(TEST_DOCUMENT);
 
-        assertEquals(2, reader.getList("objectList[*].subField").size());
+        List<String> l = reader.<String>getList("objectList[*].subField");
+
+        assertEquals(2, l.size());
 
         /*