doc: update/improve javadocs

Includes changes to in-class content, the addition of overview.html
files, and links to 3rd parties for dependency references.

Author: dmaccormack

module/jsonurl-core/src/main/java/org/jsonurl/JavaValueFactory.java

@@ -25,7 +25,14 @@
 import java.util.Set;
 
 /**
- * A {@link org.jsonurl.ValueFactory ValueFactory} based on J2SE8 data types.
+ * A {@link org.jsonurl.ValueFactory ValueFactory} based on Java SE data types.
+ * 
+ * <p>The following singletons are available:
+ * <ul>
+ * <li>{@link #PRIMITIVE}
+ * <li>{@link #DOUBLE}
+ * <li>{@link #BIGMATH}
+ * </ul>
  *
  * @author jsonurl.org
  * @author David MacCormack
@@ -42,7 +49,13 @@ public interface JavaValueFactory extends ValueFactory.TransparentBuilder<
     String> {
 
     /**
-     * A singleton instance of {@link JavaValueFactory}.
+     * A singleton instance of {@link JavaValueFactory} that stores numbers as
+     * boxed primitives.
+     * 
+     * <p>This factory uses an instance of {@link java.lang.Long Long} for
+     * (most) numbers which fall between {@link Long#MIN_VALUE} and
+     * {@link Long#MAX_VALUE}, and  an instance of
+     * {@link java.lang.Double Double} for everything else.
      */
     public static final JavaValueFactory PRIMITIVE = new JavaValueFactory() {
 
@@ -53,7 +66,8 @@ public Number getNumber(NumberText text) {
     };
 
     /**
-     * A singleton instance of {@link JavaValueFactory}.
+     * A singleton instance of {@link JavaValueFactory} that uses instances of
+     * {@link java.lang.Double Double} for all numbers.
      */
     public static final JavaValueFactory DOUBLE = new JavaValueFactory() {
 
@@ -64,7 +78,16 @@ public Number getNumber(NumberText text) {
     };
 
     /**
-     * A singleton instance of {@link JavaValueFactory}.
+     * A singleton instance of {@link JavaValueFactory} that uses
+     * {@link java.math.BigInteger BigInteger} and
+     * {@link java.math.BigDecimal BigDecimal} when necessary.
+     * 
+     * <p>When using this factory, numbers without fractional parts that are
+     * too big to be stored in a {@link java.lang.Long Long} will be stored
+     * in a {@link java.math.BigInteger BigInteger}. Numbers with fractional
+     * parts that are too big to stored in a {@link java.lang.Double Double}
+     * will be stored in a {@link java.math.BigDecimal BigDecimal}.
+     * 
      */
     public static final JavaValueFactory BIGMATH = new JavaValueFactory() {
         @Override

module/jsonurl-core/src/main/java/org/jsonurl/JavaValueParser.java

@@ -21,7 +21,7 @@
 import java.util.Map;
 
 /**
- * A {@link org.jsonurl.Parser Parser} based on J2SE8 data types.
+ * A {@link org.jsonurl.Parser Parser} based on Java SE data types.
  *
  * @author jsonurl.org
  * @author David MacCormack

module/jsonurl-core/src/main/java/org/jsonurl/JsonUrl.java

@@ -34,10 +34,8 @@
 import java.nio.charset.MalformedInputException;
 
 /**
- * The reference implementation of JSON->URL.
- * 
- * <p>This class provides static methods for performing a number of
- * actions on JSON-&gt;URL text.
+ * This class provides static methods for performing a number of
+ * actions on JSON&#x2192;URL text.
  * 
  * @author jsonurl.org
  * @author David MacCormack
@@ -75,7 +73,7 @@ private static final int percentDecode(
         /**
          * parse true, false, and null literals.
          *
-         * @return true if the string matches one of the following JSON-&gt;URL
+         * @return true if the string matches one of the following JSON&#x2192;URL
          *      literal values: true, false, null.
          */
         @SuppressWarnings("PMD")
@@ -215,7 +213,7 @@ private static final String string(
         /**
          * parse a literal value.
          * 
-         * <p>This will parse a literal value from JSON-&gt;URL text and return
+         * <p>This will parse a literal value from JSON&#x2192;URL text and return
          * it as a java.lang.String (as opposed to a ValueFactory String).
          * It will perform input validation and string literal decoding.
          *
@@ -260,7 +258,7 @@ static final String literalToJavaString(
         /**
          * parse a literal value
          * 
-         * <p>This will parse a literal value from JSON-&gt;URL text. You may use
+         * <p>This will parse a literal value from JSON&#x2192;URL text. You may use
          * {@link org.jsonurl.JsonUrl#parseLiteralLength(CharSequence, int, int)
          * parseLiteralLength} to calculate the stop index.
          *

module/jsonurl-core/src/main/java/org/jsonurl/JsonUrlStringBuilder.java

@@ -18,7 +18,7 @@
  */
 
 /**
- * A JsonUrlTextAppender that appends JSON->URL text to a StringBuilder.
+ * A JsonUrlTextAppender that appends JSON→URL text to a StringBuilder.
  *
  * @author jsonurl.org
  * @author David MacCormack

module/jsonurl-core/src/main/java/org/jsonurl/JsonUrlTextAppender.java

@@ -22,7 +22,7 @@
 import java.math.BigInteger;
 
 /**
- * A JsonTextBuilder that appends JSON->URL text to any Appendable.
+ * A JsonTextBuilder that appends JSON→URL text to any Appendable.
  * @param <A> Accumulator type
  * @param <R> Result type
  *
@@ -41,7 +41,7 @@ public abstract class JsonUrlTextAppender<A extends Appendable, R>
     /**
      * Create a new JsonUrlTextAppender.
      *
-     * @param out JSON-&gt;URL text destination
+     * @param out JSON&#x2192;URL text destination
      */
     public JsonUrlTextAppender(A out) {
         this.out = out;

module/jsonurl-core/src/main/java/org/jsonurl/NumberBuilder.java

@@ -24,8 +24,8 @@
 import java.math.BigInteger;
 
 /**
- * A NumberBuilder implements the builder pattern for JSON->URL number literals.
- * An instance of this class may be used to parse JSON->URL number
+ * A NumberBuilder implements the builder pattern for JSON→URL number literals.
+ * An instance of this class may be used to parse JSON→URL number
  * literals from text as Java SE values.
  *
  * <h2>Single Use</h2>
@@ -388,7 +388,7 @@ public boolean parse(CharSequence s, int start, int stop) {
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      *
      *<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
      * isNumber(s, 0, s.length(), false)}.
@@ -398,7 +398,7 @@ public static boolean isNumber(CharSequence s) {
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      *
      *<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
      * isNumber(s, 0, s.length(), isInteger)}.
@@ -408,26 +408,26 @@ public static boolean isNumber(CharSequence s, boolean isInteger) {
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      *
      * <p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)}
      * isNumber(s, 0, stop, false)}.
      * @param s a valid CharSequence
      * @param start an index
      * @param stop an index
-     * @return true if the CharSequence is a JSON-&gt;URL number
+     * @return true if the CharSequence is a JSON&#x2192;URL number
      */
     public static boolean isNumber(CharSequence s, int start, int stop) {
         return isNumber(s, start, stop, false);
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      * 
      * @param s a valid CharSequence
      * @param start an index
      * @param stop an index
-     * @return true if the CharSequence is a JSON-&gt;URL number
+     * @return true if the CharSequence is a JSON&#x2192;URL number
      */
     @SuppressWarnings("PMD")
     public static boolean isNumber(
@@ -494,17 +494,17 @@ public static boolean isNumber(
     }
 
     /**
-     * Determine if this text represents a valid JSON-&gt;URL number literal.
+     * Determine if this text represents a valid JSON&#x2192;URL number literal.
      *
      * <p>This is the result of calling {@link #parse(CharSequence, int, int)}.
-     * @return true if this text represents is a JSON-&gt;URL number literal
+     * @return true if this text represents is a JSON&#x2192;URL number literal
      */
     public boolean isNumber() {
         return this.intIndexStop > this.intIndexStart;
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      *
      *<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
      * isNumber(s, 0, s.length(), true)}.
@@ -514,7 +514,7 @@ public static boolean isInteger(CharSequence s) {
     }
 
     /**
-     * Determine if the given CharSequence is a valid JSON-&gt;URL number literal.
+     * Determine if the given CharSequence is a valid JSON&#x2192;URL number literal.
      *
      *<p>Convenience for {@link #isNumber(CharSequence, int, int, boolean)
      * isNumber(s, start, stop, true)}.

module/jsonurl-core/src/main/java/org/jsonurl/NumberText.java

@@ -18,7 +18,7 @@
  */
 
 /**
- * NumberText provides access to a parsed JSON->URL number literal.
+ * NumberText provides access to a parsed JSON→URL number literal.
  *
  * <p>The text of a number is broken down into three parts: integer part,
  * fractional part, and exponent. These parts may be accessed via start and stop

module/jsonurl-core/src/main/java/org/jsonurl/ParseException.java

@@ -18,7 +18,7 @@
  */
 
 /**
- * An exception that occurs while parsing JSON->URL text.
+ * An exception that occurs while parsing JSON→URL text.
  */
 public class ParseException extends RuntimeException {
 

module/jsonurl-core/src/main/java/org/jsonurl/Parser.java

@@ -37,9 +37,9 @@
 import java.util.Set;
 
 /**
- * A JSON->URL parser.
+ * A JSON→URL text parser.
  * 
- * <p>An instance of this class may be used to parse JSON-&gt;URL text and
+ * <p>An instance of this class may be used to parse JSON&#x2192;URL text and
  * instantiate JVM heap objects. The interface allows you to control the
  * types and values of the Objects created.
  *
@@ -197,7 +197,7 @@ public J parseObject(CharSequence s) {
     /**
      * Parse a character sequence.
      *
-     * <p>Parse the given JSON-&gt;URL text and return an object.
+     * <p>Parse the given JSON&#x2192;URL text and return an object.
      * @param s the text to be parsed
      * @param off offset of the first character to be parsed
      * @param length the number of characters to be parsed
@@ -223,7 +223,7 @@ public A parseArray(CharSequence s) {
     /**
      * Parse a character sequence.
      *
-     * <p>Parse the given JSON-&gt;URL text and return an array.
+     * <p>Parse the given JSON&#x2192;URL text and return an array.
      * @param s the text to be parsed
      * @param off offset of the first character to be parsed
      * @param length the number of characters to be parsed
@@ -248,7 +248,7 @@ public V parse(CharSequence s) {
     /**
      * Parse a character sequence.
      *
-     * <p>Parse the given JSON-&gt;URL text and return a typed value.
+     * <p>Parse the given JSON&#x2192;URL text and return a typed value.
      * @param s the text to be parsed
      * @param off offset of the first character to be parsed
      * @param length the number of characters to be parsed
@@ -279,7 +279,7 @@ public V parse(CharSequence s, ValueType canReturn) {
     /**
      * Parse a character sequence.
      *
-     * <p>Parse the given JSON-&gt;URL text and return a typed value.
+     * <p>Parse the given JSON&#x2192;URL text and return a typed value.
      * @param s the text to be parsed
      * @param off offset of the first character to be parsed
      * @param length the number of characters to be parsed

module/jsonurl-core/src/main/java/org/jsonurl/SyntaxException.java

@@ -18,7 +18,7 @@
  */
 
 /**
- * A syntax error in JSON->URL text. 
+ * A syntax error in JSON→URL text. 
  */
 public class SyntaxException extends ParseException {