Adding comments

stleary · Dec 24, 2023 · 7701f21 · 7701f21
1 parent ffd48af
commit 7701f21
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 8 deletions.
diff --git a/src/main/java/org/json/JSONArray.java b/src/main/java/org/json/JSONArray.java
@@ -152,11 +152,29 @@ public JSONArray(Collection<?> collection) {
       this(collection, 0, new JSONParserConfiguration());
     }
 
+    /**
+     * Construct a JSONArray from a Collection.
+     *
+     * @param collection
+     *            A Collection.
+     * @param jsonParserConfiguration
+     *            Configuration object for the JSON parser
+     */
     public JSONArray(Collection<?> collection, JSONParserConfiguration jsonParserConfiguration) {
         this(collection, 0, jsonParserConfiguration);
     }
 
-    protected JSONArray(Collection<?> collection, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
+    /**
+     * Construct a JSONArray from a collection with recursion depth.
+     *
+     * @param collection
+     *             A Collection.
+     * @param recursionDepth
+     *             Variable for tracking the count of nested object creations.
+     * @param jsonParserConfiguration
+     *             Configuration object for the JSON parser
+     */
+    JSONArray(Collection<?> collection, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
         if (recursionDepth > jsonParserConfiguration.getMaxNestingDepth()) {
           throw new JSONException("JSONArray has reached recursion depth limit of " + jsonParserConfiguration.getMaxNestingDepth());
         }
@@ -1362,7 +1380,7 @@ public JSONArray put(int index, Map<?, ?> value) throws JSONException {
      * @param value
      *          The Map value.
      * @param jsonParserConfiguration
-     *          Configuration for recursive depth
+     *          Configuration object for the JSON parser
      * @return
      * @throws JSONException
      *          If the index is negative or if the value is an invalid
@@ -1811,8 +1829,7 @@ public boolean isEmpty() {
      *            {@code true} to call {@link JSONObject#wrap(Object)} for each item,
      *            {@code false} to add the items directly
      * @param recursionDepth
-     *            variable to keep the count of how nested the object creation is happening.
-     *            
+     *            Variable for tracking the count of nested object creations.
      */
     private void addAll(Collection<?> collection, boolean wrap, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
         this.myArrayList.ensureCapacity(this.myArrayList.size() + collection.size());
@@ -1852,8 +1869,14 @@ private void addAll(Iterable<?> iter, boolean wrap) {
      * Add an array's elements to the JSONArray.
      *
      * @param array
+     *          Array. If the parameter passed is null, or not an array,
+     *          JSONArray, Collection, or Iterable, an exception will be
+     *          thrown.
      * @param wrap
+     *          {@code true} to call {@link JSONObject#wrap(Object)} for each item,
+     *          {@code false} to add the items directly
      * @throws JSONException
+     *          If not an array or if an array value is non-finite number.
      */
     private void addAll(Object array, boolean wrap) throws JSONException {
       this.addAll(array, wrap, 0);
@@ -1867,7 +1890,10 @@ private void addAll(Object array, boolean wrap) throws JSONException {
      *            JSONArray, Collection, or Iterable, an exception will be
      *            thrown.
      * @param wrap
+     *          {@code true} to call {@link JSONObject#wrap(Object)} for each item,
+     *          {@code false} to add the items directly
      * @param recursionDepth
+     *          Variable for tracking the count of nested object creations.
      */
     private void addAll(Object array, boolean wrap, int recursionDepth) {
         addAll(array, wrap, recursionDepth, new JSONParserConfiguration());
@@ -1883,8 +1909,8 @@ private void addAll(Object array, boolean wrap, int recursionDepth) {
      *            {@code true} to call {@link JSONObject#wrap(Object)} for each item,
      *            {@code false} to add the items directly
      * @param recursionDepth
-     *            Variable to keep the count of how nested the object creation is happening.
-     * @param recursionDepth
+     *            Variable for tracking the count of nested object creations.
+     * @param jsonParserConfiguration
      *            Variable to pass parser custom configuration for json parsing.
      * @throws JSONException
      *            If not an array or if an array value is non-finite number.

diff --git a/src/main/java/org/json/JSONObject.java b/src/main/java/org/json/JSONObject.java
@@ -279,6 +279,15 @@ public JSONObject(Map<?, ?> m) {
       this(m, 0, new JSONParserConfiguration());
     }
 
+    /**
+     * Construct a JSONObject from a Map with custom json parse configurations.
+     *
+     * @param m
+     *            A map object that can be used to initialize the contents of
+     *            the JSONObject.
+     * @param jsonParserConfiguration
+     *            Variable to pass parser custom configuration for json parsing.
+     */
     public JSONObject(Map<?, ?> m, JSONParserConfiguration jsonParserConfiguration) {
         this(m, 0, jsonParserConfiguration);
     }
@@ -287,7 +296,7 @@ public JSONObject(Map<?, ?> m, JSONParserConfiguration jsonParserConfiguration)
      * Construct a JSONObject from a map with recursion depth.
      *
      */
-    protected JSONObject(Map<?, ?> m, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
+    private JSONObject(Map<?, ?> m, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
         if (recursionDepth > jsonParserConfiguration.getMaxNestingDepth()) {
           throw new JSONException("JSONObject has reached recursion depth limit of " + jsonParserConfiguration.getMaxNestingDepth());
         }
@@ -2581,7 +2590,23 @@ public static Object wrap(Object object) {
         return wrap(object, null);
     }
 
-    public static Object wrap(Object object, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
+    /**
+     * Wrap an object, if necessary. If the object is <code>null</code>, return the NULL
+     * object. If it is an array or collection, wrap it in a JSONArray. If it is
+     * a map, wrap it in a JSONObject. If it is a standard property (Double,
+     * String, et al) then it is already wrapped. Otherwise, if it comes from
+     * one of the java packages, turn it into a string. And if it doesn't, try
+     * to wrap it in a JSONObject. If the wrapping fails, then null is returned.
+     *
+     * @param object
+     *            The object to wrap
+     * @param recursionDepth
+     *            Variable for tracking the count of nested object creations.
+     * @param jsonParserConfiguration
+     *            Variable to pass parser custom configuration for json parsing.
+     * @return The wrapped value
+     */
+    static Object wrap(Object object, int recursionDepth, JSONParserConfiguration jsonParserConfiguration) {
       return wrap(object, null, recursionDepth, jsonParserConfiguration);
     }