Merge pull request stleary#854 from jscrdev/fixed-javadocs

Enhanced documentation for Java classes

Author: stleary

pom.xml

@@ -126,6 +126,9 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
                 <version>3.5.0</version>
+                <configuration>
+                    <source>8</source>
+                </configuration>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>

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

@@ -148,6 +148,11 @@ public String toString() {
      */
     private final Map<String, Object> map;
 
+    /**
+     * Retrieves the type of the underlying Map in this class.
+     *
+     * @return The class object representing the type of the underlying Map.
+     */
     public Class<? extends Map> getMapType() {
         return map.getClass();
     }
@@ -369,7 +374,6 @@ private JSONObject(Map<?, ?> m, int recursionDepth, JSONParserConfiguration json
      * &#64;JSONPropertyIgnore
      * public String getName() { return this.name; }
      * </pre>
-     * <p>
      *
      * @param bean
      *            An object that has getter methods that should be used to make
@@ -2232,6 +2236,14 @@ public static String quote(String string) {
         }
     }
 
+    /**
+     * Quotes a string and appends the result to a given Writer.
+     *
+     * @param string The input string to be quoted.
+     * @param w      The Writer to which the quoted string will be appended.
+     * @return The same Writer instance after appending the quoted string.
+     * @throws IOException If an I/O error occurs while writing to the Writer.
+     */
     public static Writer quote(String string, Writer w) throws IOException {
         if (string == null || string.isEmpty()) {
             w.write("\"\"");

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

@@ -163,6 +163,12 @@ public JSONPointer(final String pointer) {
         //}
     }
 
+    /**
+     * Constructs a new JSONPointer instance with the provided list of reference tokens.
+     *
+     * @param refTokens A list of strings representing the reference tokens for the JSON Pointer.
+     *                  Each token identifies a step in the path to the targeted value.
+     */
     public JSONPointer(List<String> refTokens) {
         this.refTokens = new ArrayList<String>(refTokens);
     }

src/main/java/org/json/JSONPointerException.java

@@ -14,10 +14,21 @@
 public class JSONPointerException extends JSONException {
     private static final long serialVersionUID = 8872944667561856751L;
 
+    /**
+     * Constructs a new JSONPointerException with the specified error message.
+     *
+     * @param message The detail message describing the reason for the exception.
+     */
     public JSONPointerException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new JSONPointerException with the specified error message and cause.
+     *
+     * @param message The detail message describing the reason for the exception.
+     * @param cause   The cause of the exception.
+     */
     public JSONPointerException(String message, Throwable cause) {
         super(message, cause);
     }

src/main/java/org/json/JSONTokener.java

@@ -525,6 +525,11 @@ public String toString() {
                 this.line + "]";
     }
 
+    /**
+     * Closes the underlying reader, releasing any resources associated with it.
+     *
+     * @throws IOException If an I/O error occurs while closing the reader.
+     */
     public void close() throws IOException {
         if(reader!=null){
             reader.close();

src/main/java/org/json/ParserConfiguration.java

@@ -29,11 +29,20 @@ public class ParserConfiguration {
      */
     protected int maxNestingDepth;
 
+    /**
+     * Constructs a new ParserConfiguration with default settings.
+     */
     public ParserConfiguration() {
         this.keepStrings = false;
         this.maxNestingDepth = DEFAULT_MAXIMUM_NESTING_DEPTH;
     }
 
+    /**
+     * Constructs a new ParserConfiguration with the specified settings.
+     *
+     * @param keepStrings     A boolean indicating whether to preserve strings during parsing.
+     * @param maxNestingDepth An integer representing the maximum allowed nesting depth.
+     */
     protected ParserConfiguration(final boolean keepStrings, final int maxNestingDepth) {
         this.keepStrings = keepStrings;
         this.maxNestingDepth = maxNestingDepth;

src/main/java/org/json/XML.java

@@ -56,6 +56,9 @@ public class XML {
      */
     public static final String NULL_ATTR = "xsi:nil";
 
+    /**
+     * Represents the XML attribute name for specifying type information.
+     */
     public static final String TYPE_ATTR = "xsi:type";
 
     /**

src/main/java/org/json/XMLParserConfiguration.java

@@ -352,9 +352,20 @@ public XMLParserConfiguration withShouldTrimWhitespace(boolean shouldTrimWhiteSp
         return clonedConfiguration;
     }
 
+    /**
+     * Checks if the parser should automatically close empty XML tags.
+     *
+     * @return {@code true} if empty XML tags should be automatically closed, {@code false} otherwise.
+     */
     public boolean isCloseEmptyTag() {
         return this.closeEmptyTag;
     }
+
+    /**
+     * Checks if the parser should trim white spaces from XML content.
+     *
+     * @return {@code true} if white spaces should be trimmed, {@code false} otherwise.
+     */
     public boolean shouldTrimWhiteSpace() {
         return this.shouldTrimWhiteSpace;
     }

src/main/java/org/json/XMLXsiTypeConverter.java

@@ -42,5 +42,12 @@
  * @param <T> return type of convert method
  */
 public interface XMLXsiTypeConverter<T> {
+
+    /**
+     * Converts an XML xsi:type attribute value to the specified type {@code T}.
+     *
+     * @param value The string representation of the XML xsi:type attribute value to be converted.
+     * @return An object of type {@code T} representing the converted value.
+     */
     T convert(String value);
 }