Merge pull request #40 from bowbahdoe/cleanup-feb-20

Document a bunch of methods

Author: bowbahdoe

README.md

@@ -16,15 +16,15 @@ Requires Java 17+.
 <dependency>
     <groupId>dev.mccue</groupId>
     <artifactId>json</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
 </dependency>
 ```
 
 ### Gradle
 
 ```
 dependencies {
-    implementation("dev.mccue:json:0.2.0")
+    implementation("dev.mccue:json:0.2.1")
 }
 ```
 

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>dev.mccue</groupId>
     <artifactId>json</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
     <packaging>jar</packaging>
 
     <properties>

src/main/java/dev/mccue/json/Json.java

@@ -6,6 +6,7 @@
 
 import java.io.*;
 import java.math.BigDecimal;
+import java.math.BigInteger;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.LinkedHashMap;
@@ -14,17 +15,43 @@
 
 /**
  * <p>
- *     Immutable tree representation of Json.
+ *     Immutable tree representation of the json data model.
  * </p>
  *
  * <p>
- *     There are no shared methods between the various implementors, so this class just serves the purpose
- *     of giving them a common supertype.
+ *     The allowed implementors represent the different possible shapes Json can take.
+ * </p>
+ *
+ * <ul>
+ *     <li>{@link JsonObject} - A map of {@link String} to {@link Json}.</li>
+ *     <li>{@link JsonArray} - An array of {@link Json}.</li>
+ *     <li>{@link JsonString} - A string.</li>
+ *     <li>{@link JsonNumber} - A number.</li>
+ *     <li>{@link JsonTrue} - true.</li>
+ *     <li>{@link JsonFalse} - false.</li>
+ *     <li>{@link JsonNull} - null.</li>
+ * </ul>
+ *
+ * <p>
+ *     There are no shared methods between those implementors, so this class just serves the purpose
+ *     of giving them a common supertype and to be a place for associated static methods.
+ * </p>
+ *
+ * <p>
+ *     Unless otherwise specified, all factory methods in this interface are null-safe and will replace
+ *     any actual nulls with {@link JsonNull}.
  * </p>
  */
 public sealed interface Json
         extends Serializable, JsonEncodable
         permits JsonBoolean, JsonNull, JsonString, JsonNumber, JsonArray, JsonObject {
+    /**
+     * Creates {@link Json} from something which implements {@link JsonEncodable},
+     * including {@link Json} itself.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(JsonEncodable value) {
         if (value == null) {
             return JsonNull.instance();
@@ -40,86 +67,190 @@ static Json of(JsonEncodable value) {
         }
     }
 
+    /**
+     * Creates {@link Json} from a {@link BigDecimal}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(BigDecimal value) {
         return value == null ? JsonNull.instance() : new BigDecimalImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from a double.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(double value) {
         return new DoubleImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from a long.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(long value) {
         return new LongImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from a float.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(float value) {
         return new DoubleImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from an int.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(int value) {
         return new LongImpl(value);
     }
 
-    static Json of(java.lang.Double value) {
+    /**
+     * Creates {@link Json} from a {@link Double}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(Double value) {
         return value == null ? JsonNull.instance() : new DoubleImpl(value);
     }
 
-    static Json of(java.lang.Long value) {
+    /**
+     * Creates {@link Json} from a {@link Long}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(Long value) {
         return value == null ? JsonNull.instance() : new LongImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from a {@link Float}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(Float value) {
         return value == null ? JsonNull.instance() : new DoubleImpl(value);
     }
 
+    /**
+     * Creates {@link Json} from an {@link Integer}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
     static Json of(Integer value) {
         return value == null ? JsonNull.instance() : new LongImpl(value);
     }
 
-    static Json of(java.math.BigInteger value) {
+    /**
+     * Creates {@link Json} from a {@link BigInteger}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(BigInteger value) {
         return value == null ? JsonNull.instance() : new BigIntegerImpl(value);
     }
 
-    static Json of(java.lang.String value) {
+    /**
+     * Creates {@link Json} from a {@link String}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(String value) {
         return value == null ? JsonNull.instance() : new StringImpl(value);
     }
 
+    /**
+     * Creates {@link Json} representing null.
+     * @return {@link Json} representing null.
+     */
     static Json ofNull() {
         return JsonNull.instance();
     }
 
+    /**
+     * Creates {@link Json} representing true.
+     * @return {@link Json} representing true.
+     */
     static Json ofTrue() {
         return JsonBoolean.of(true);
     }
 
+    /**
+     * Creates a {@link Json} representing false.
+     * @return {@link Json} representing false.
+     */
     static Json ofFalse() {
         return JsonBoolean.of(false);
     }
 
 
-    static Json of(boolean b) {
-        return JsonBoolean.of(b);
+    /**
+     * Creates {@link Json} from a boolean.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(boolean value) {
+        return JsonBoolean.of(value);
     }
 
-    static Json of(java.lang.Boolean b) {
-        return b == null ? JsonNull.instance() : JsonBoolean.of(b);
+    /**
+     * Creates {@link Json} from a {@link Boolean}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(Boolean value) {
+        return value == null ? JsonNull.instance() : JsonBoolean.of(value);
     }
 
-    static Json of(Collection<? extends JsonEncodable> jsonList) {
-        return jsonList == null
+    /**
+     * Creates {@link Json} from a {@link Collection} of items which
+     * implement {@link JsonEncodable}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(Collection<? extends JsonEncodable> value) {
+        return value == null
                 ? JsonNull.instance()
                 : new ArrayImpl(
-                        jsonList.stream()
+                        value.stream()
                                 .map(json -> json == null ? JsonNull.instance() : json.toJson())
                                 .toList()
                 );
     }
 
-    static Json of(Map<java.lang.String, ? extends JsonEncodable> jsonMap) {
-        return jsonMap == null
+    /**
+     * Creates {@link Json} from a {@link Map} with {@link String} keys to values which
+     * implement {@link JsonEncodable}.
+     *
+     * @param value The value to be encoded.
+     * @return An instance of {@link Json}.
+     */
+    static Json of(Map<String, ? extends JsonEncodable> value) {
+        return value == null
                 ? JsonNull.instance()
                 : new ObjectImpl(
-                        jsonMap
+                        value
                                 .entrySet()
                                 .stream()
                                 .collect(Collectors.toUnmodifiableMap(
@@ -131,17 +262,29 @@ static Json of(Map<java.lang.String, ? extends JsonEncodable> jsonMap) {
                 );
     }
 
+    /**
+     * Creates a new {@link JsonObject.Builder}.
+     *
+     * @return A new {@link JsonObject.Builder}.
+     */
     static JsonObject.Builder objectBuilder() {
         return JsonObject.builder();
     }
 
-    static JsonObject.Builder objectBuilder(Map<java.lang.String, ? extends JsonEncodable> object) {
-        if (object instanceof JsonObject o) {
+    /**
+     * Creates a new {@link JsonObject.Builder} pre-filled with elements from a {@link Map}
+     * with {@link String} keys and values which implement {@link JsonEncodable}.
+     *
+     * @param value The value to pre-fill the builder with.
+     * @return A new {@link JsonObject.Builder}.
+     */
+    static JsonObject.Builder objectBuilder(Map<String, ? extends JsonEncodable> value) {
+        if (value instanceof JsonObject o) {
             return new ObjectBuilder(new LinkedHashMap<>(o));
         }
         else {
             var objectEntries = new LinkedHashMap<String, Json>();
-            for (var entry : object.entrySet()) {
+            for (var entry : value.entrySet()) {
                 objectEntries.put(entry.getKey(), Json.of(entry.getValue()));
             }
             return new ObjectBuilder(objectEntries);
@@ -193,12 +336,30 @@ static JsonObject emptyObject() {
         return ObjectImpl.EMPTY;
     }
 
+    /**
+     * Vacuous implementation to make methods like {@link Json#of(java.util.Collection)}
+     * and {@link Json#of(java.util.Map)} convenient to create.
+     *
+     * @return Itself.
+     */
     @Override
     default Json toJson() {
         return this;
     }
 
 
+    /**
+     * Reads the given text as {@link Json}
+     *
+     * <p>
+     *     Only expects to read a single form. Will throw if there is non-whitespace content
+     *     at the end.
+     * </p>
+     *
+     * @param jsonText The text to read.
+     * @return {@link Json}
+     * @throws JsonReadException If the input {@link Json} is malformed.
+     */
     static Json readString(CharSequence jsonText) throws JsonReadException {
         return readString(jsonText, new JsonReadOptions());
     }

src/main/java/dev/mccue/json/JsonArray.java

@@ -10,6 +10,9 @@
 import java.util.List;
 import java.util.Objects;
 
+/**
+ * Represents an array in the json data model.
+ */
 public sealed interface JsonArray extends Json, List<Json> permits ArrayImpl {
     static JsonArray of(Json... values) {
         return of(Arrays.asList(values));

src/main/java/dev/mccue/json/JsonBoolean.java

@@ -1,8 +1,26 @@
 package dev.mccue.json;
 
+import dev.mccue.json.internal.ValueCandidate;
+
+/**
+ * Represents a boolean in the json data model.
+ */
+@ValueCandidate
 public sealed interface JsonBoolean extends Json, Comparable<JsonBoolean> permits JsonFalse, JsonTrue {
+    /**
+     * Returns true or false.
+     *
+     * @return true or false.
+     */
     boolean value();
 
+    /**
+     * Creates a {@link JsonBoolean} from the given value. Guaranteed to be comparable with ==,
+     * but not to be safe for identity sensitive operations.
+     *
+     * @param value The boolean to wrap.
+     * @return A {@link JsonBoolean}.
+     */
     static JsonBoolean of(boolean value) {
         return value ? JsonTrue.instance() : JsonFalse.instance();
     }

src/main/java/dev/mccue/json/JsonDecoder.java

@@ -6,8 +6,7 @@
 import java.util.function.Function;
 
 /**
- * A Decoder is some code that knows how to transform Json into
- * some other type.
+ * An object that knows how to convert another kind of object can be converted to JSON.
  *
  * <p>
  *     It is preferred that when a decoder fails it throw a {@link JsonDecodeException}.