From 99c84fdf3a7f4218734a3b2e4b1e36d5ecb60601 Mon Sep 17 00:00:00 2001 From: Valentyn Kolesnikov Date: Fri, 2 Feb 2024 09:07:48 +0200 Subject: [PATCH] Enhanced documentation for Java classes --- pom.xml | 3 +++ src/main/java/org/json/JSONObject.java | 14 +++++++++++++- src/main/java/org/json/JSONPointer.java | 6 ++++++ src/main/java/org/json/JSONPointerException.java | 11 +++++++++++ src/main/java/org/json/JSONTokener.java | 5 +++++ src/main/java/org/json/ParserConfiguration.java | 9 +++++++++ src/main/java/org/json/XML.java | 3 +++ src/main/java/org/json/XMLParserConfiguration.java | 11 +++++++++++ src/main/java/org/json/XMLXsiTypeConverter.java | 7 +++++++ 9 files changed, 68 insertions(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 7196978..1488f49 100644 --- a/pom.xml +++ b/pom.xml @@ -126,6 +126,9 @@ org.apache.maven.plugins maven-javadoc-plugin 3.5.0 + + 8 + attach-javadocs diff --git a/src/main/java/org/json/JSONObject.java b/src/main/java/org/json/JSONObject.java index 039f136..4c08b0b 100644 --- a/src/main/java/org/json/JSONObject.java +++ b/src/main/java/org/json/JSONObject.java @@ -148,6 +148,11 @@ public class JSONObject { */ private final Map map; + /** + * Retrieves the type of the underlying Map in this class. + * + * @return The class object representing the type of the underlying Map. + */ public Class getMapType() { return map.getClass(); } @@ -369,7 +374,6 @@ public class JSONObject { * @JSONPropertyIgnore * public String getName() { return this.name; } * - *

* * @param bean * An object that has getter methods that should be used to make @@ -2232,6 +2236,14 @@ public class JSONObject { } } + /** + * 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("\"\""); diff --git a/src/main/java/org/json/JSONPointer.java b/src/main/java/org/json/JSONPointer.java index 963fdec..91bd137 100644 --- a/src/main/java/org/json/JSONPointer.java +++ b/src/main/java/org/json/JSONPointer.java @@ -163,6 +163,12 @@ public class JSONPointer { //} } + /** + * 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 refTokens) { this.refTokens = new ArrayList(refTokens); } diff --git a/src/main/java/org/json/JSONPointerException.java b/src/main/java/org/json/JSONPointerException.java index a0e128c..dc5a25a 100644 --- a/src/main/java/org/json/JSONPointerException.java +++ b/src/main/java/org/json/JSONPointerException.java @@ -14,10 +14,21 @@ Public Domain. 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); } diff --git a/src/main/java/org/json/JSONTokener.java b/src/main/java/org/json/JSONTokener.java index 4a83a69..0bc6dfb 100644 --- a/src/main/java/org/json/JSONTokener.java +++ b/src/main/java/org/json/JSONTokener.java @@ -525,6 +525,11 @@ public class JSONTokener { 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(); diff --git a/src/main/java/org/json/ParserConfiguration.java b/src/main/java/org/json/ParserConfiguration.java index ede2fc5..5cdc10d 100644 --- a/src/main/java/org/json/ParserConfiguration.java +++ b/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; diff --git a/src/main/java/org/json/XML.java b/src/main/java/org/json/XML.java index 9d42bb3..301c8ba 100644 --- a/src/main/java/org/json/XML.java +++ b/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"; /** diff --git a/src/main/java/org/json/XMLParserConfiguration.java b/src/main/java/org/json/XMLParserConfiguration.java index 5087aa1..bc4a800 100644 --- a/src/main/java/org/json/XMLParserConfiguration.java +++ b/src/main/java/org/json/XMLParserConfiguration.java @@ -352,9 +352,20 @@ public class XMLParserConfiguration extends ParserConfiguration { 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; } diff --git a/src/main/java/org/json/XMLXsiTypeConverter.java b/src/main/java/org/json/XMLXsiTypeConverter.java index 0011eff..ea6739d 100644 --- a/src/main/java/org/json/XMLXsiTypeConverter.java +++ b/src/main/java/org/json/XMLXsiTypeConverter.java @@ -42,5 +42,12 @@ Public Domain. * @param return type of convert method */ public interface XMLXsiTypeConverter { + + /** + * 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); }