~ Global reformatting

src/ch/feuermurmel/json/Json.java

@@ -10,8 +10,10 @@ private Json() {
 	}
 
 	/**
-	 Shortcut for {@link JsonList#create()}.<p/>
-	 Returns a new, empty {@link JsonList}. Useful using a static import for this class. This method is useful when used in a way like this:<p/>
+	 Shortcut for {@link JsonList#create()}.
+	 <p/>
+	 Returns a new, empty {@link JsonList}. Useful using a static import for this class. This method is useful when used in a way like this:
+	 <p/>
 	 {@code JsonList list = list().add(1).add(2).add("three");}
 
 	 @return a new, empty JsonList.
@@ -21,8 +23,10 @@ public static JsonList list() {
 	}
 
 	/**
-	 Shortcut for {@link JsonMap#create()}.<p/>
-	 Returns a new, empty {@link JsonMap}. Useful using a static import for this class. This method is useful when used in a way like this:<p/>
+	 Shortcut for {@link JsonMap#create()}.
+	 <p/>
+	 Returns a new, empty {@link JsonMap}. Useful using a static import for this class. This method is useful when used in a way like this:
+	 <p/>
 	 {@code JsonMap map = map().add("one", 1).add("two", 2);}
 
 	 @return a new, empty JsonList.
@@ -32,13 +36,20 @@ public static JsonMap map() {
 	}
 
 	/**
-	 This method either casts or converts an object to a subclass of {@link JsonObject}.<p/>
-	 If the passed object is a subclass of JsonObject it will be cast. If the object implements {@link JsonConvertible}, it's {@link JsonConvertible#toJson()} method wil be called. Other types will be converted according to this list:<p/>
-	 - {@code null} will be converted to {@link JsonNull}.<p/>
-	 - {@code boolean} and instances of {@code Boolean} will be converted to {@link JsonBoolean}.<p/>
-	 - {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, {@code double} and instances of their boxed variants will be converted to {@link JsonNumber}.<p/>
-	 - {@code char} and instances of {@code Character} and {@code String} will be converted to {@link JsonString}.<p/>
-	 - Instances of {@link Map} will be converted to {@link JsonMap}. Their keys will be converted using {@code toString()}, their values using this method.<p/>
+	 This method either casts or converts an object to a subclass of {@link JsonObject}.
+	 <p/>
+	 If the passed object is a subclass of JsonObject it will be cast. If the object implements {@link JsonConvertible}, it's {@link JsonConvertible#toJson()} method wil be called. Other types will be converted according to this list:
+	 <p/>
+	 - {@code null} will be converted to {@link JsonNull}.
+	 <p/>
+	 - {@code boolean} and instances of {@code Boolean} will be converted to {@link JsonBoolean}.
+	 <p/>
+	 - {@code byte}, {@code short}, {@code int}, {@code long}, {@code float}, {@code double} and instances of their boxed variants will be converted to {@link JsonNumber}.
+	 <p/>
+	 - {@code char} and instances of {@code Character} and {@code String} will be converted to {@link JsonString}.
+	 <p/>
+	 - Instances of {@link Map} will be converted to {@link JsonMap}. Their keys will be converted using {@code toString()}, their values using this method.
+	 <p/>
 	 - Instances of {@link Iterable} will be converted to {@link List}. Their elements will be converted using this method.
 
 	 @param obj The object to convert.
@@ -95,7 +106,8 @@ public static JsonObject convert(Object obj) {
 	}
 
 	/**
-	 Parse a JSON document into a {@link JsonObject}.<p/>
+	 Parse a JSON document into a {@link JsonObject}.
+	 <p/>
 	 Will parse the document according to the JSON document syntax. Can also be used on the output of {@link JsonObject#toString()} or {@link JsonObject#prettyPrint()}.
 
 	 @param input The string to parse. May contain leading or trailing whitespace.
@@ -111,12 +123,14 @@ public static JsonObject parse(String input) throws JsonParseException {
 	}
 
 	/**
-	 Parse a JSON document read from a {@link Reader}.<p/>
+	 Parse a JSON document read from a {@link Reader}.
+	 <p/>
 	 Currently, the stream has to end after the document or parsing will fail.
 
 	 @param input Source to read from, e.g. an {@link InputStreamReader}.
 	 @return the parsed {@link JsonObject}.
 	 @throws JsonParseException if invalid syntax is encountered.
+	 @throws IOException it the passed {@code Reader} throws an {@code IOException}.
 	 */
 	public static JsonObject parse(Reader input) throws IOException, JsonParseException {
 		return new Parser(input).result;

src/ch/feuermurmel/json/JsonBoolean.java

@@ -47,7 +47,7 @@ public JsonBoolean clone() {
 
 	private static final JsonBoolean falseInstance = new JsonBoolean(false);
 	private static final JsonBoolean trueInstance = new JsonBoolean(true);
-	
+
 	public static JsonBoolean instance(boolean value) {
 		return value ? trueInstance : falseInstance;
 	}

src/ch/feuermurmel/json/JsonList.java

@@ -67,6 +67,7 @@ public JsonList remove(int index) {
 	 Get the object at the specified index.
 
 	 @param index Index of the element to return.
+	 @throws IndexOutOfBoundsException if the index is out of range.
 	 */
 	public JsonObject get(int index) {
 		return data.get(index);
@@ -148,22 +149,18 @@ public JsonList clone() {
 		return res;
 	}
 
-	/**
-	 Create and return an empty {@code JsonList}.
-	 */
+	/** Create and return an empty {@code JsonList}. */
 	public static JsonList create() {
 		return new JsonList();
 	}
 
-	/**
-	 Create and return a {@code JsonList} and initialize with the contents of {@code contents}.
-	 */
+	/** Create and return a {@code JsonList} and initialize with the contents of {@code contents}. */
 	public static JsonList create(Iterable<?> content) {
 		JsonList list = new JsonList();
-		
+
 		for (Object i : content)
 			list.add(i);
-		
+
 		return list;
 	}
 }

src/ch/feuermurmel/json/JsonMap.java

@@ -37,6 +37,7 @@ public JsonMap put(String k, Object v) {
 	 Get the value for the specified key.
 
 	 @param k Key that maps to the returned value.
+	 @throws IllegalArgumentException if the key is not in the map.
 	 */
 	public JsonObject get(String k) {
 		JsonObject res = data.get(k);
@@ -70,12 +71,12 @@ public JsonMap remove(String k) {
 		return this;
 	}
 
-	/** returns whether the map contains a mapping with the specified key. */
+	/** Returns whether the map contains a mapping with the specified key. */
 	public boolean has(String k) {
 		return data.containsKey(k);
 	}
 
-	/** Number of key-value-pais in the map. */
+	/** Number of key-value-pairs in the map. */
 	public int size() {
 		return data.size();
 	}
@@ -110,7 +111,7 @@ public void toString(Appendable dest) throws IOException {
 			JsonString.instance(i.getKey()).toString(dest);
 			dest.append(":");
 			i.getValue().toString(dest);
-			
+
 			sep = ",";
 		}
 
@@ -140,16 +141,13 @@ public JsonMap clone() {
 		return res;
 	}
 
-	/**
-	 Create and return an empty {@code JsonMap}.
-	 */
+	/** Create and return an empty {@code JsonMap}. */
 	public static JsonMap create() {
 		return new JsonMap();
 	}
 
-	/**
-	 Create and return a {@code JsonList} and initialize with the contents of {@code contents}.
-	 */
+	/** Create and return a {@code JsonList} and initialize with the contents of {@code contents}. */
+	// FIXME: Keys that are instances of JsonString will have quotes added before being used as keys in this JsonMap
 	public static JsonMap create(Map<?, ?> content) {
 		JsonMap map = new JsonMap();
 

src/ch/feuermurmel/json/JsonNull.java

@@ -27,6 +27,6 @@ public int hashCode() {
 	public JsonNull clone() {
 		return this;
 	}
-	
+
 	public static final JsonNull instance = new JsonNull();
 }

src/ch/feuermurmel/json/JsonNumber.java

@@ -13,17 +13,17 @@ public abstract class JsonNumber extends JsonObject {
 	public boolean equals(Object obj) {
 		if (obj instanceof JsonNumber)
 			return ((JsonObject) obj).asDouble() == asDouble();
-		
+
 		return false;
 	}
 
 	/**
 	 Return whether this {@link JsonNumber} contains an integral value.
-	 
+
 	 @returns {@code true} if the JSON number is internaly represented by a long, false if the JSON number is internaly represented by a double.
 	 */
 	public abstract boolean isIntegral();
-	
+
 	/**
 	 Create a JsonNumber using an integral value.
 
@@ -44,11 +44,11 @@ public static JsonNumber instance(double value) {
 
 	private static final class Long extends JsonNumber {
 		private final long value;
-		
+
 		private Long(long value) {
 			this.value = value;
 		}
-		
+
 		@Override
 		public boolean isIntegral() {
 			return true;
@@ -76,7 +76,7 @@ public String toString() {
 		public boolean equals(Object obj) {
 			if (obj instanceof Long)
 				return ((Long) obj).value == value;
-				
+
 			return super.equals(obj);
 		}
 

src/ch/feuermurmel/json/JsonObject.java

@@ -2,7 +2,6 @@
 
 import java.io.IOException;
 import java.io.OutputStreamWriter;
-import java.nio.ByteBuffer;
 
 /**
  Super class of all classes implementing the different JSON datatypes.
@@ -16,17 +15,11 @@ public abstract class JsonObject implements JsonConvertible, Cloneable {
 	 Compare this JSON object to another JSON object.
 	 <p/>
 	 The passed object will not converted to a JSON object, so only an object of the same class will compare equal.
-	 <p/>
-	 Overrides {@link Object#equals(Object)}
 	 */
 	@Override
 	public abstract boolean equals(Object obj);
 
-	/**
-	 Return the hash code of this JSON object.
-	 <p/>
-	 Overrides {@link Object#hashCode()}
-	 */
+	/** Return the hash code of this JSON object. */
 	@Override
 	public abstract int hashCode();
 
@@ -49,17 +42,14 @@ public String toString() {
 		return builder.toString();
 	}
 
-	/**
-	 Write this object as a JSON document to an instance of {@code Appendable} like {@link StringBuilder} or {@link OutputStreamWriter}.
-	 */
+	/** Write this object as a JSON document to an instance of {@code Appendable} like {@link StringBuilder} or {@link OutputStreamWriter}. */
 	@SuppressWarnings("DesignForExtension")
 	public void toString(Appendable dest) throws IOException {
 		dest.append(toString());
 	}
 
-	// FIXME: `convert' is misleading
 	/**
-	 Convert this JSON object to a Java boolean.
+	 Return the value of an instance of {@link JsonBoolean} as a {@code boolean}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonBoolean}.
 	 */
@@ -69,7 +59,7 @@ public boolean asBoolean() {
 	}
 
 	/**
-	 Convert this JSON object to a Java long.
+	 Return the value of an instance of {@link JsonNumber} as a {@code long}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonNumber}.
 	 */
@@ -79,7 +69,7 @@ public long asLong() {
 	}
 
 	/**
-	 Convert this JSON object to a Java int.
+	 Return the value of an instance of {@link JsonNumber} as an {@code int}. This will truncate values that are out of range.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonNumber}.
 	 */
@@ -88,7 +78,7 @@ public final int asInt() {
 	}
 
 	/**
-	 Convert this JSON object to a Java double.
+	 Return the value of an instance of {@link JsonNumber} as a {@code double}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonNumber}.
 	 */
@@ -98,7 +88,7 @@ public double asDouble() {
 	}
 
 	/**
-	 Convert this JSON object to a Java float.
+	 Return the value of an instance of {@link JsonNumber} as a {@code float}. This will truncate {@link JsonNumber} values that are out of range.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonNumber}.
 	 */
@@ -107,7 +97,7 @@ public final float asFloat() {
 	}
 
 	/**
-	 Convert this JSON object to a Java String.
+	 Return the value of an instance of {@link JsonString} as a {@link String}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonString}.
 	 */
@@ -117,7 +107,7 @@ public String asString() {
 	}
 
 	/**
-	 Cast this JSON object to a {@link JsonString}.
+	 Cast this JSON object to a {@link JsonList}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonString}.
 	 */
@@ -127,7 +117,7 @@ public JsonList asList() {
 	}
 
 	/**
-	 Convert this JSON object to a {@link JsonMap}.
+	 Cast this JSON object to a {@link JsonMap}.
 
 	 @throws UnsupportedTypeException when this object is not an instance of {@link JsonMap}.
 	 */
@@ -139,9 +129,7 @@ public JsonMap asMap() {
 	/**
 	 Return a JsonObject with same content as this one.
 	 <p/>
-	 Instances of mutable JSON classes will be deep-cloned, while instances of immutable classes this will return their own instance.
-	 <p/>
-	 Overrides {@link Object#clone()}
+	 Instances of mutable JSON classes will be deep-cloned, while instances of immutable classes this will return themselves instance.
 	 */
 	@SuppressWarnings("DesignForExtension")
 	@Override

src/ch/feuermurmel/json/JsonString.java

@@ -29,7 +29,7 @@ public String asString() {
 	@Override
 	public void toString(Appendable dest) throws IOException {
 		dest.append("\"");
-		
+
 		for (int i = 0; i < value.length(); i += 1) {
 			char c = value.charAt(i);
 
@@ -67,7 +67,7 @@ public int hashCode() {
 	public JsonString clone() {
 		return this;
 	}
-	
+
 	public static JsonString instance(String value) {
 		return new JsonString(value);
 	}