From 30c1bd16bac7ceb41bce719b44faf22b465c9907 Mon Sep 17 00:00:00 2001 From: "John J. Aylward" Date: Tue, 2 Oct 2018 13:38:19 -0400 Subject: [PATCH] fix javadoc --- JSONArray.java | 53 +++++++++++++++++++++++++++--------------- JSONObject.java | 61 ++++++++++++++++++++++++++++++------------------- 2 files changed, 73 insertions(+), 41 deletions(-) diff --git a/JSONArray.java b/JSONArray.java index 9314438..b7ae565 100644 --- a/JSONArray.java +++ b/JSONArray.java @@ -180,10 +180,16 @@ public class JSONArray implements Iterable { } /** - * Construct a JSONArray from an array + * Construct a JSONArray from an array. + * + * @param array + * Array. If the parameter passed is null, or not an array, an + * exception will be thrown. * * @throws JSONException - * If not an array or if an array value is non-finite number. + * If not an array or if an array value is non-finite number. + * @throws NullPointerException + * Thrown if the array parameter is null. */ public JSONArray(Object array) throws JSONException { this(); @@ -310,17 +316,19 @@ public class JSONArray implements Iterable { } /** - * Get the enum value associated with an index. - * - * @param clazz - * The type of enum to retrieve. - * @param index - * The index must be between 0 and length() - 1. - * @return The enum value at the index location - * @throws JSONException - * if the key is not found or if the value cannot be converted - * to an enum. - */ + * Get the enum value associated with an index. + * + * @param + * Enum Type + * @param clazz + * The type of enum to retrieve. + * @param index + * The index must be between 0 and length() - 1. + * @return The enum value at the index location + * @throws JSONException + * if the key is not found or if the value cannot be converted + * to an enum. + */ public > E getEnum(Class clazz, int index) throws JSONException { E val = optEnum(clazz, index); if(val==null) { @@ -334,7 +342,10 @@ public class JSONArray implements Iterable { } /** - * Get the BigDecimal value associated with an index. + * Get the BigDecimal value associated with an index. If the value is float + * or double, the the {@link BigDecimal#BigDecimal(double)} constructor + * will be used. See notes on the constructor for conversion issues that + * may arise. * * @param index * The index must be between 0 and length() - 1. @@ -683,6 +694,8 @@ public class JSONArray implements Iterable { /** * Get the enum value associated with a key. * + * @param + * Enum Type * @param clazz * The type of enum to retrieve. * @param index @@ -696,6 +709,8 @@ public class JSONArray implements Iterable { /** * Get the enum value associated with a key. * + * @param + * Enum Type * @param clazz * The type of enum to retrieve. * @param index @@ -725,7 +740,6 @@ public class JSONArray implements Iterable { } } - /** * Get the optional BigInteger value associated with an index. The * defaultValue is returned if there is no value for the index, or if the @@ -745,7 +759,10 @@ public class JSONArray implements Iterable { /** * Get the optional BigDecimal value associated with an index. The * defaultValue is returned if there is no value for the index, or if the - * value is not a number and cannot be converted to a number. + * value is not a number and cannot be converted to a number. If the value + * is float or double, the the {@link BigDecimal#BigDecimal(double)} + * constructor will be used. See notes on the constructor for conversion + * issues that may arise. * * @param index * The index must be between 0 and length() - 1. @@ -1192,8 +1209,8 @@ public class JSONArray implements Iterable { } /** - * Uses a uaer initialized JSONPointer and tries to - * match it to an item whithin this JSONArray. For example, given a + * Uses a user initialized JSONPointer and tries to + * match it to an item within this JSONArray. For example, given a * JSONArray initialized with this document: * 
      * [
diff --git a/JSONObject.java b/JSONObject.java
index 1a9b9de..67ae9c7 100644
--- a/JSONObject.java
+++ b/JSONObject.java
@@ -576,17 +576,19 @@ public class JSONObject {
     }
 
     /**
-    * Get the enum value associated with a key.
-    * 
-    * @param clazz
-    *           The type of enum to retrieve.
-    * @param key
-    *           A key string.
-    * @return The enum value associated with the key
-    * @throws JSONException
-    *             if the key is not found or if the value cannot be converted
-    *             to an enum.
-    */
+     * Get the enum value associated with a key.
+     * 
+     * @param 
+     *            Enum Type
+     * @param clazz
+     *           The type of enum to retrieve.
+     * @param key
+     *           A key string.
+     * @return The enum value associated with the key
+     * @throws JSONException
+     *             if the key is not found or if the value cannot be converted
+     *             to an enum.
+     */
     public > E getEnum(Class clazz, String key) throws JSONException {
         E val = optEnum(clazz, key);
         if(val==null) {
@@ -814,6 +816,8 @@ public class JSONObject {
     /**
      * Get an array of field names from a JSONObject.
      *
+     * @param jo
+     *            JSON object
      * @return An array of field names, or null if there are no names.
      */
     public static String[] getNames(JSONObject jo) {
@@ -824,8 +828,10 @@ public class JSONObject {
     }
 
     /**
-     * Get an array of field names from an Object.
+     * Get an array of public field names from an Object.
      *
+     * @param object
+     *            object to read
      * @return An array of field names, or null if there are no names.
      */
     public static String[] getNames(Object object) {
@@ -1036,6 +1042,8 @@ public class JSONObject {
     /**
      * Get the enum value associated with a key.
      * 
+     * @param 
+     *            Enum Type
      * @param clazz
      *            The type of enum to retrieve.
      * @param key
@@ -1049,6 +1057,8 @@ public class JSONObject {
     /**
      * Get the enum value associated with a key.
      * 
+     * @param 
+     *            Enum Type
      * @param clazz
      *            The type of enum to retrieve.
      * @param key
@@ -1137,9 +1147,10 @@ public class JSONObject {
     }
 
     /**
-     * @param defaultValue
-     * @param val
-     * @return
+     * @param val value to convert
+     * @param defaultValue default value to return is the conversion doesn't work or is null.
+     * @return BigDecimal conversion of the original value, or the defaultValue if unable
+     *          to convert. 
      */
     static BigDecimal objectToBigDecimal(Object val, BigDecimal defaultValue) {
         if (NULL.equals(val)) {
@@ -1187,9 +1198,10 @@ public class JSONObject {
     }
 
     /**
-     * @param defaultValue
-     * @param val
-     * @return
+     * @param val value to convert
+     * @param defaultValue default value to return is the conversion doesn't work or is null.
+     * @return BigInteger conversion of the original value, or the defaultValue if unable
+     *          to convert. 
      */
     static BigInteger objectToBigInteger(Object val, BigInteger defaultValue) {
         if (NULL.equals(val)) {
@@ -1859,8 +1871,10 @@ public class JSONObject {
      * are both non-null, and only if there is not already a member with that
      * name.
      *
-     * @param key string
-     * @param value object
+     * @param key
+     *            key to insert into
+     * @param value
+     *            value to insert
      * @return this.
      * @throws JSONException
      *             if the key is a duplicate
@@ -1971,9 +1985,10 @@ public class JSONObject {
 
     /**
      * Produce a string in double quotes with backslash sequences in all the
-     * right places. A backslash will be inserted within