gradle support

Author: stleary

src/main/java/org/json/CDL.java

@@ -98,7 +98,7 @@ private static String getValue(JSONTokener x) throws JSONException {
      * Produce a JSONArray of strings from a row of comma delimited values.
      * @param x A JSONTokener of the source text.
      * @return A JSONArray of strings.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONArray rowToJSONArray(JSONTokener x) throws JSONException {
         JSONArray ja = new JSONArray();
@@ -134,7 +134,7 @@ public static JSONArray rowToJSONArray(JSONTokener x) throws JSONException {
      *  method.
      * @param x A JSONTokener of the source text.
      * @return A JSONObject combining the names and values.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONObject rowToJSONObject(JSONArray names, JSONTokener x)
             throws JSONException {
@@ -184,7 +184,7 @@ public static String rowToString(JSONArray ja) {
      * using the first row as a source of names.
      * @param string The comma delimited text.
      * @return A JSONArray of JSONObjects.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONArray toJSONArray(String string) throws JSONException {
         return toJSONArray(new JSONTokener(string));
@@ -195,7 +195,7 @@ public static JSONArray toJSONArray(String string) throws JSONException {
      * using the first row as a source of names.
      * @param x The JSONTokener containing the comma delimited text.
      * @return A JSONArray of JSONObjects.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONArray toJSONArray(JSONTokener x) throws JSONException {
         return toJSONArray(rowToJSONArray(x), x);
@@ -207,7 +207,7 @@ public static JSONArray toJSONArray(JSONTokener x) throws JSONException {
      * @param names A JSONArray of strings.
      * @param string The comma delimited text.
      * @return A JSONArray of JSONObjects.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONArray toJSONArray(JSONArray names, String string)
             throws JSONException {
@@ -220,7 +220,7 @@ public static JSONArray toJSONArray(JSONArray names, String string)
      * @param names A JSONArray of strings.
      * @param x A JSONTokener of the source text.
      * @return A JSONArray of JSONObjects.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONArray toJSONArray(JSONArray names, JSONTokener x)
             throws JSONException {
@@ -248,7 +248,7 @@ public static JSONArray toJSONArray(JSONArray names, JSONTokener x)
      * JSONObject.
      * @param ja A JSONArray of JSONObjects.
      * @return A comma delimited text.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static String toString(JSONArray ja) throws JSONException {
         JSONObject jo = ja.optJSONObject(0);
@@ -268,7 +268,7 @@ public static String toString(JSONArray ja) throws JSONException {
      * @param names A JSONArray of strings.
      * @param ja A JSONArray of JSONObjects.
      * @return A comma delimited text.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static String toString(JSONArray names, JSONArray ja)
             throws JSONException {

src/main/java/org/json/Cookie.java

@@ -76,7 +76,7 @@ public static String escape(String string) {
      * @param string The cookie specification string.
      * @return A JSONObject containing "name", "value", and possibly other
      *  members.
-     * @throws JSONException
+     * @throws JSONException if a called function fails or a syntax error
      */
     public static JSONObject toJSONObject(String string) throws JSONException {
         String         name;
@@ -113,7 +113,7 @@ public static JSONObject toJSONObject(String string) throws JSONException {
      * All other members are ignored.
      * @param jo A JSONObject
      * @return A cookie specification string
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static String toString(JSONObject jo) throws JSONException {
         StringBuilder sb = new StringBuilder();

src/main/java/org/json/CookieList.java

@@ -42,7 +42,7 @@ public class CookieList {
      *     cookieJSONObject.getString("value"));
      * @param string  A cookie list string
      * @return A JSONObject
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONObject toJSONObject(String string) throws JSONException {
         JSONObject jo = new JSONObject();
@@ -63,7 +63,7 @@ public static JSONObject toJSONObject(String string) throws JSONException {
      * in the names and values are replaced by "%hh".
      * @param jo A JSONObject
      * @return A cookie list string
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static String toString(JSONObject jo) throws JSONException {
         boolean             b = false;

src/main/java/org/json/HTTP.java

@@ -51,12 +51,12 @@ public class HTTP {
      *    "Reason-Phrase": "OK" (for example)
      * }</pre>
      * In addition, the other parameters in the header will be captured, using
-     * the HTTP field names as JSON names, so that <pre>
+     * the HTTP field names as JSON names, so that <pre>{@code
      *    Date: Sun, 26 May 2002 18:06:04 GMT
      *    Cookie: Q=q2=PPEAsg--; B=677gi6ouf29bn&b=2&f=s
-     *    Cache-Control: no-cache</pre>
+     *    Cache-Control: no-cache}</pre>
      * become
-     * <pre>{...
+     * <pre>{@code
      *    Date: "Sun, 26 May 2002 18:06:04 GMT",
      *    Cookie: "Q=q2=PPEAsg--; B=677gi6ouf29bn&b=2&f=s",
      *    "Cache-Control": "no-cache",
@@ -66,7 +66,7 @@ public class HTTP {
      * @param string An HTTP header string.
      * @return A JSONObject containing the elements and attributes
      * of the XML string.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public static JSONObject toJSONObject(String string) throws JSONException {
         JSONObject     jo = new JSONObject();

src/main/java/org/json/HTTPTokener.java

@@ -43,8 +43,8 @@ public HTTPTokener(String string) {
 
     /**
      * Get the next token or string. This is used in parsing HTTP headers.
-     * @throws JSONException
      * @return A String.
+     * @throws JSONException if a syntax error occurs
      */
     public String nextToken() throws JSONException {
         char c;

src/main/java/org/json/JSONArray.java

@@ -1333,7 +1333,7 @@ public String toString() {
     /**
      * Make a pretty-printed JSON text of this JSONArray.
      * 
-     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * <p>If <pre> {@code indentFactor > 0}</pre> and the {@link JSONArray} has only
      * one element, then the array will be output on a single line:
      * <pre>{@code [1]}</pre>
      * 
@@ -1355,7 +1355,7 @@ public String toString() {
      *         object, beginning with <code>[</code>&nbsp;<small>(left
      *         bracket)</small> and ending with <code>]</code>
      *         &nbsp;<small>(right bracket)</small>.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public String toString(int indentFactor) throws JSONException {
         StringWriter sw = new StringWriter();
@@ -1370,9 +1370,9 @@ public String toString(int indentFactor) throws JSONException {
      * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
      *</b>
-     *
+     * @param writer the writer object
      * @return The writer.
-     * @throws JSONException
+     * @throws JSONException if a called function fails
      */
     public Writer write(Writer writer) throws JSONException {
         return this.write(writer, 0, 0);
@@ -1381,7 +1381,7 @@ public Writer write(Writer writer) throws JSONException {
     /**
      * Write the contents of the JSONArray as JSON text to a writer.
      * 
-     * <p>If <code>indentFactor > 0</code> and the {@link JSONArray} has only
+     * <p>If <pre>{@code indentFactor > 0}</pre> and the {@link JSONArray} has only
      * one element, then the array will be output on a single line:
      * <pre>{@code [1]}</pre>
      * 
@@ -1404,7 +1404,7 @@ public Writer write(Writer writer) throws JSONException {
      * @param indent
      *            The indentation of the top level.
      * @return The writer.
-     * @throws JSONException
+     * @throws JSONException if a called function fails or unable to write
      */
     public Writer write(Writer writer, int indentFactor, int indent)
             throws JSONException {

src/main/java/org/json/JSONML.java

@@ -41,7 +41,7 @@ public class JSONML {
      *     if we are at the outermost level.
      * @param keepStrings	Don't type-convert text nodes and attribute values
      * @return A JSONArray if the value is the outermost tag, otherwise null.
-     * @throws JSONException
+     * @throws JSONException if a parsing error occurs
      */
     private static Object parse(
         XMLTokener x,
@@ -238,7 +238,7 @@ private static Object parse(
      * attributes, then the second element will be JSONObject containing the
      * name/value pairs. If the tag contains children, then strings and
      * JSONArrays will represent the child tags.
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param string The source string.
      * @return A JSONArray containing the structured data from the XML string.
      * @throws JSONException Thrown on error converting to a JSONArray
@@ -258,7 +258,7 @@ public static JSONArray toJSONArray(String string) throws JSONException {
      * As opposed to toJSONArray this method does not attempt to convert 
      * any text node or attribute value to any type 
      * but just leaves it as a string.
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param string The source string.
      * @param keepStrings If true, then values will not be coerced into boolean
      *  or numeric values and will instead be left as strings
@@ -280,7 +280,7 @@ public static JSONArray toJSONArray(String string, boolean keepStrings) throws J
      * As opposed to toJSONArray this method does not attempt to convert 
      * any text node or attribute value to any type 
      * but just leaves it as a string.
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param x An XMLTokener.
      * @param keepStrings If true, then values will not be coerced into boolean
      *  or numeric values and will instead be left as strings
@@ -299,7 +299,7 @@ public static JSONArray toJSONArray(XMLTokener x, boolean keepStrings) throws JS
      * attributes, then the second element will be JSONObject containing the
      * name/value pairs. If the tag contains children, then strings and
      * JSONArrays will represent the child content and tags.
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param x An XMLTokener.
      * @return A JSONArray containing the structured data from the XML string.
      * @throws JSONException Thrown on error converting to a JSONArray
@@ -317,7 +317,7 @@ public static JSONArray toJSONArray(XMLTokener x) throws JSONException {
      * contains children, the object will have a "childNodes" property which
      * will be an array of strings and JsonML JSONObjects.
 
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param string The XML source text.
      * @return A JSONObject containing the structured data from the XML string.
      * @throws JSONException Thrown on error converting to a JSONObject
@@ -335,7 +335,7 @@ public static JSONObject toJSONObject(String string) throws JSONException {
      * contains children, the object will have a "childNodes" property which
      * will be an array of strings and JsonML JSONObjects.
 
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param string The XML source text.
      * @param keepStrings If true, then values will not be coerced into boolean
      *  or numeric values and will instead be left as strings
@@ -355,7 +355,7 @@ public static JSONObject toJSONObject(String string, boolean keepStrings) throws
      * contains children, the object will have a "childNodes" property which
      * will be an array of strings and JsonML JSONObjects.
 
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param x An XMLTokener of the XML source text.
      * @return A JSONObject containing the structured data from the XML string.
      * @throws JSONException Thrown on error converting to a JSONObject
@@ -373,7 +373,7 @@ public static JSONObject toJSONObject(XMLTokener x) throws JSONException {
      * contains children, the object will have a "childNodes" property which
      * will be an array of strings and JsonML JSONObjects.
 
-     * Comments, prologs, DTDs, and <code>&lt;[ [ ]]></code> are ignored.
+     * Comments, prologs, DTDs, and <pre>{@code &lt;[ [ ]]>}</pre> are ignored.
      * @param x An XMLTokener of the XML source text.
      * @param keepStrings If true, then values will not be coerced into boolean
      *  or numeric values and will instead be left as strings

src/main/java/org/json/JSONObject.java

@@ -2288,16 +2288,16 @@ public String toString() {
     /**
      * Make a pretty-printed JSON text of this JSONObject.
      * 
-     * <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
+     * <p>If <pre>{@code indentFactor > 0}</pre> and the {@link JSONObject}
      * has only one key, then the object will be output on a single line:
      * <pre>{@code {"key": 1}}</pre>
      * 
      * <p>If an object has 2 or more keys, then it will be output across
-     * multiple lines: <code><pre>{
+     * multiple lines: <pre>{@code {
      *  "key1": 1,
      *  "key2": "value 2",
      *  "key3": 3
-     * }</pre></code>
+     * }}</pre>
      * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
      * </b>
@@ -2409,9 +2409,9 @@ public static Object wrap(Object object) {
      * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
      * </b>
-     * 
+     * @param writer the writer object
      * @return The writer.
-     * @throws JSONException
+     * @throws JSONException if a called function has an error
      */
     public Writer write(Writer writer) throws JSONException {
         return this.write(writer, 0, 0);
@@ -2470,16 +2470,16 @@ static final void indent(Writer writer, int indent) throws IOException {
     /**
      * Write the contents of the JSONObject as JSON text to a writer.
      * 
-     * <p>If <code>indentFactor > 0</code> and the {@link JSONObject}
+     * <p>If <pre>{@code indentFactor > 0}</pre> and the {@link JSONObject}
      * has only one key, then the object will be output on a single line:
      * <pre>{@code {"key": 1}}</pre>
      * 
      * <p>If an object has 2 or more keys, then it will be output across
-     * multiple lines: <code><pre>{
+     * multiple lines: <pre>{@code {
      *  "key1": 1,
      *  "key2": "value 2",
      *  "key3": 3
-     * }</pre></code>
+     * }}</pre>
      * <p><b>
      * Warning: This method assumes that the data structure is acyclical.
      * </b>
@@ -2491,7 +2491,8 @@ static final void indent(Writer writer, int indent) throws IOException {
      * @param indent
      *            The indentation of the top level.
      * @return The writer.
-     * @throws JSONException
+     * @throws JSONException if a called function has an error or a write error
+     * occurs
      */
     public Writer write(Writer writer, int indentFactor, int indent)
             throws JSONException {

src/main/java/org/json/JSONPointer.java

@@ -68,6 +68,7 @@ public static class Builder {
         /**
          * Creates a {@code JSONPointer} instance using the tokens previously set using the
          * {@link #append(String)} method calls.
+         * @return a JSONPointer object
          */
         public JSONPointer build() {
             return new JSONPointer(this.refTokens);
@@ -277,6 +278,7 @@ private static String escape(String token) {
     /**
      * Returns a string representing the JSONPointer path value using URI
      * fragment identifier representation
+     * @return a uri fragment string
      */
     public String toURIFragment() {
         try {

src/main/java/org/json/JSONWriter.java

@@ -93,6 +93,7 @@ public class JSONWriter {
 
     /**
      * Make a fresh JSONWriter. It can be used to build one JSON text.
+     * @param w an appendable object
      */
     public JSONWriter(Appendable w) {
         this.comma = false;
@@ -373,7 +374,7 @@ public static String valueToString(Object value) throws JSONException {
      * <code>false</code>.
      * @param b A boolean.
      * @return this
-     * @throws JSONException
+     * @throws JSONException if a called function has an error
      */
     public JSONWriter value(boolean b) throws JSONException {
         return this.append(b ? "true" : "false");
@@ -393,7 +394,7 @@ public JSONWriter value(double d) throws JSONException {
      * Append a long value.
      * @param l A long.
      * @return this
-     * @throws JSONException
+     * @throws JSONException if a called function has an error
      */
     public JSONWriter value(long l) throws JSONException {
         return this.append(Long.toString(l));