improve javadoc

Author: rbygrave

jsonb/src/main/java/io/avaje/jsonb/JsonType.java

@@ -8,7 +8,32 @@
 /**
  * Provides API to serialise a type to and from JSON.
  * <p>
- * JsonType provides the main API that is used to convert to and from json.
+ * JsonType provides the main API used to read and write json.
+ *
+ * <h4>fromJson</h4>
+ * <p>
+ * Read json content from: String, byte[], Reader, InputStream, JsonReader
+ * </p>
+ * <pre>{@code
+ *
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
+ *
+ *  Customer customer = customerType.fromJson(content);
+ *
+ * }</pre>
+ *
+ * <h4>toJson</h4>
+ * <p>
+ * Write json content to: String, byte[], Writer, OutputStream, JsonWriter
+ * </p>
+ * <pre>{@code
+ *
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
+ *
+ *  String asJson = customerType.toJson(customer);
+ *
+ * }</pre>
+ *
  * <p>
  * Moshi note: JsonType does not exist in Moshi and has been added to provide a
  * slightly nicer API to use than JsonAdapter.

jsonb/src/main/java/io/avaje/jsonb/Jsonb.java

@@ -12,19 +12,43 @@
 /**
  * Provides access to json adapters by type.
  *
- * <pre>{@code
+ * <h4>Initialise with defaults</h3>
  *
+ * <pre>{@code
  *   Jsonb jsonb = Jsonb.newBuilder().build();
+ * }</pre>
  *
- *   JsonType<Customer> customerType = jsonb.type(Customer.class);
+ * <h4>Initialise with some configuration</h3>
  *
- *   Customer customer = ...;
+ * <pre>{@code
+ *   Jsonb jsonb = Jsonb.newBuilder()
+ *     .serializeNulls(true)
+ *     .serializeEmpty(true)
+ *     .failOnUnknown(true)
+ *     .build();
+ * }</pre>
+ *
+ * <h4>fromJson</h4>
+ * <p>
+ * Read json content from: String, byte[], Reader, InputStream, JsonReader
+ * </p>
+ * <pre>{@code
+ *
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
+ *
+ *  Customer customer = customerType.fromJson(content);
+ *
+ * }</pre>
+ *
+ * <h4>toJson</h4>
+ * <p>
+ * Write json content to: String, byte[], Writer, OutputStream, JsonWriter
+ * </p>
+ * <pre>{@code
  *
- *   // write json
- *   String asJson = customerType.toJson(customer);
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
  *
- *   // read json
- *   Customer customer = customerType.fromJson(asJson);
+ *  String asJson = customerType.toJson(customer);
  *
  * }</pre>
  */
@@ -38,6 +62,16 @@ public interface Jsonb {
    * <p>
    * Note that JsonAdapter's that are generated are automatically registered via service
    * loading so there is no need to explicitly register those generated JsonAdapters.
+   *
+   * <pre>{@code
+   *
+   *   Jsonb jsonb = Jsonb.newBuilder()
+   *     .serializeNulls(true)
+   *     .serializeEmpty(true)
+   *     .failOnUnknown(true)
+   *     .build();
+   *
+   * }</pre>
    */
   static Builder newBuilder() {
     Iterator<Bootstrap> bootstrapService = ServiceLoader.load(Bootstrap.class).iterator();

jsonb/src/main/java/io/avaje/jsonb/core/DefaultBootstrap.java

@@ -2,8 +2,14 @@
 
 import io.avaje.jsonb.Jsonb;
 
+/**
+ * Default bootstrap of Jsonb.
+ */
 public class DefaultBootstrap {
 
+  /**
+   * Create the Jsonb.Builder.
+   */
   public static Jsonb.Builder newBuilder() {
     return new DJsonb.DBuilder();
   }

jsonb/src/main/java/io/avaje/jsonb/core/Util.java

@@ -19,6 +19,9 @@
 import java.lang.reflect.*;
 import java.util.*;
 
+/**
+ * Utility methods for defining Types.
+ */
 public final class Util {
 
   static final Type[] EMPTY_TYPE_ARRAY = new Type[]{};

jsonb/src/main/java/io/avaje/jsonb/core/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Core internal implementation.
+ */
+package io.avaje.jsonb.core;

jsonb/src/main/java/io/avaje/jsonb/jackson/JacksonAdapter.java

@@ -13,13 +13,19 @@
 
 import java.io.*;
 
+/**
+ * Jackson Core implementation of IOAdapter.
+ */
 public class JacksonAdapter implements IOAdapter {
 
   private final JsonFactory jsonFactory;
   private final boolean serializeNulls;
   private final boolean serializeEmpty;
   private final boolean failOnUnknown;
 
+  /**
+   * Create with the given default configuration.
+   */
   public JacksonAdapter(boolean serializeNulls, boolean serializeEmpty, boolean failOnUnknown) {
     this.serializeNulls = serializeNulls;
     this.serializeEmpty = serializeEmpty;

jsonb/src/main/java/io/avaje/jsonb/jackson/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Uses Jackson Core JsonGenerator and JsonParser to implement the SPI.
+ */
+package io.avaje.jsonb.jackson;

jsonb/src/main/java/io/avaje/jsonb/package-info.java

@@ -0,0 +1,47 @@
+/**
+ * Core API of Jsonb.
+ *
+ * <h4>Initialise with defaults</h3>
+ *
+ * <pre>{@code
+ *   Jsonb jsonb = Jsonb.newBuilder().build();
+ * }</pre>
+ *
+ * <h4>Initialise with some configuration</h3>
+ *
+ * <pre>{@code
+ *   Jsonb jsonb = Jsonb.newBuilder()
+ *     .serializeNulls(true)
+ *     .serializeEmpty(true)
+ *     .failOnUnknown(true)
+ *     .build();
+ * }</pre>
+ *
+ * <h4>fromJson</h4>
+ * <p>
+ * Read json content from: String, byte[], Reader, InputStream, JsonReader
+ * </p>
+ * <pre>{@code
+ *
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
+ *
+ *  Customer customer = customerType.fromJson(content);
+ *
+ * }</pre>
+ *
+ * <h4>toJson</h4>
+ * <p>
+ * Write json content to: String, byte[], Writer, OutputStream, JsonWriter
+ * </p>
+ * <pre>{@code
+ *
+ *  JsonType<Customer> customerType = jsonb.type(Customer.class);
+ *
+ *  String asJson = customerType.toJson(customer);
+ *
+ * }</pre>
+ *
+ * @see io.avaje.jsonb.Jsonb
+ * @see io.avaje.jsonb.JsonType
+ */
+package io.avaje.jsonb;

jsonb/src/main/java/io/avaje/jsonb/spi/Bootstrap.java

@@ -2,7 +2,15 @@
 
 import io.avaje.jsonb.Jsonb;
 
+/**
+ * Bootstrap Jsonb.
+ */
 public interface Bootstrap {
 
+  /**
+   * Create and return a Builder (with an underling SPI implementation).
+   * <p>
+   * The default implementation uses Jackson Core.
+   */
   Jsonb.Builder newBuilder();
 }

jsonb/src/main/java/io/avaje/jsonb/spi/DelegateJsonWriter.java

@@ -2,9 +2,11 @@
 
 import io.avaje.jsonb.JsonWriter;
 
-import java.io.IOException;
 import java.math.BigDecimal;
 
+/**
+ * Provides a delegating JsonWriter.
+ */
 public abstract class DelegateJsonWriter implements JsonWriter {
 
   protected final JsonWriter delegate;