javadoc improvements

core/src/main/java/org/everit/json/schema/ArraySchema.java

@@ -49,7 +49,14 @@ public static class Builder extends Schema.Builder<ArraySchema> {
     private Schema schemaOfAdditionalItems;
 
     /**
-     * Adds an item schema for tuple validation.
+     * Adds an item schema for tuple validation. The array items of the subject under validation
+     * will be matched to expected schemas by their index. In other words the {n}th
+     * {@code addItemSchema()} invocation defines the expected schema of the {n}th item of the array
+     * being validated.
+     *
+     * @param itemSchema
+     *          the schema of the next item.
+     * @return this
      */
     public Builder addItemSchema(final Schema itemSchema) {
       if (itemSchemas == null) {
@@ -122,6 +129,9 @@ public static Builder builder() {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          contains validation criteria.
    */
   public ArraySchema(final Builder builder) {
     super(builder);

core/src/main/java/org/everit/json/schema/CombinedSchema.java

@@ -72,6 +72,12 @@ public interface ValidationCriterion {
     /**
      * Throws a {@link ValidationException} if the implemented criterion is not fulfilled by the
      * {@code subschemaCount} and the {@code matchingSubschemaCount}.
+     *
+     * @param subschemaCount
+     *          the total number of checked subschemas
+     * @param matchingSubschemaCount
+     *          the number of subschemas which successfully validated the subject (did not throw
+     *          {@link ValidationException})
      */
     void validate(int subschemaCount, int matchingSubschemaCount);
 
@@ -126,6 +132,9 @@ public static Builder oneOf(final Collection<Schema> schemas) {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          the builder containing the validation criterion and the subschemas to be checked
    */
   public CombinedSchema(final Builder builder) {
     super(builder);

core/src/main/java/org/everit/json/schema/NumberSchema.java

@@ -107,6 +107,9 @@ public NumberSchema() {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          the builder object containing validation criteria
    */
   public NumberSchema(final Builder builder) {
     super(builder);

core/src/main/java/org/everit/json/schema/ObjectComparator.java

@@ -28,6 +28,12 @@ public final class ObjectComparator {
 
   /**
    * Deep-equals implementation on primitive wrappers, {@link JSONObject} and {@link JSONArray}.
+   *
+   * @param obj1
+   *          the first object to be inspected
+   * @param obj2
+   *          the second object to be inspected
+   * @return {@code true} if the two objects are equal, {@code false} otherwise
    */
   public static boolean deepEquals(final Object obj1, final Object obj2) {
     if (obj1 instanceof JSONArray) {

core/src/main/java/org/everit/json/schema/ObjectSchema.java

@@ -81,6 +81,13 @@ public Builder patternProperty(final String pattern, final Schema schema) {
 
     /**
      * Adds a property schema.
+     *
+     * @param propName
+     *          the name of the property which' expected schema must be {@code schema}
+     * @param schema
+     *          if the subject under validation has a property named {@code propertyName} then its
+     *          value will be validated using this {@code schema}
+     * @return {@code this}
      */
     public Builder addPropertySchema(final String propName, final Schema schema) {
       Objects.requireNonNull(propName, "propName cannot be null");
@@ -111,6 +118,14 @@ public Builder minProperties(final Integer minProperties) {
 
     /**
      * Adds a property dependency.
+     *
+     * @param ifPresent
+     *          the name of the property which if is present then a property with name
+     *          {@code mustBePresent} is mandatory
+     * @param mustBePresent
+     *          a property with this name must exist in the subject under validation if a property
+     *          named {@code ifPresent} exists
+     * @return {@code this}
      */
     public Builder propertyDependency(final String ifPresent, final String mustBePresent) {
       Set<String> dependencies = propertyDependencies.get(ifPresent);
@@ -160,6 +175,9 @@ public static Builder builder() {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          the builder object containing validation criteria
    */
   public ObjectSchema(final Builder builder) {
     super(builder);

core/src/main/java/org/everit/json/schema/ReferenceSchema.java

@@ -16,9 +16,9 @@
 package org.everit.json.schema;
 
 /**
- * This class is used by {@link org.everit.json.schema.loader.SchemaLoader} to resolve JSON
- * pointers during the construction of the schema. This class has been made mutable to permit the
- * loading of recursive schemas.
+ * This class is used by {@link org.everit.json.schema.loader.SchemaLoader} to resolve JSON pointers
+ * during the construction of the schema. This class has been made mutable to permit the loading of
+ * recursive schemas.
  */
 public class ReferenceSchema extends Schema {
 
@@ -68,6 +68,9 @@ public Schema getReferredSchema() {
   /**
    * Called by {@link org.everit.json.schema.loader.SchemaLoader#load()} to set the referred root
    * schema after completing the loading process of the entire schema document.
+   *
+   * @param referredSchema
+   *          the referred schema
    */
   public void setReferredSchema(final Schema referredSchema) {
     if (this.referredSchema != null) {

core/src/main/java/org/everit/json/schema/Schema.java

@@ -65,6 +65,9 @@ public Builder<S> id(final String id) {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          the builder containing the optional title, description and id attributes of the schema
    */
   protected Schema(final Builder<?> builder) {
     this.title = builder.title;

core/src/main/java/org/everit/json/schema/StringSchema.java

@@ -25,7 +25,7 @@ public class StringSchema extends Schema {
   /**
    * Builder class for {@link StringSchema}.
    */
-  public static class Builder extends Schema.Builder {
+  public static class Builder extends Schema.Builder<StringSchema> {
 
     private Integer minLength;
 
@@ -80,6 +80,9 @@ public StringSchema() {
 
   /**
    * Constructor.
+   *
+   * @param builder
+   *          the builder object containing validation criteria
    */
   public StringSchema(final Builder builder) {
     super(builder);

core/src/main/java/org/everit/json/schema/loader/SchemaClient.java

@@ -19,15 +19,13 @@
 import java.util.function.Function;
 
 /**
- * This interface is used by {@link SchemaLoader} and {@link JSONPointer} to fetch the contents
- * denoted by remote JSON pointer.
+ * This interface is used by {@link SchemaLoader} to fetch the contents denoted by remote JSON
+ * pointer.
  *
  * <p>
  * Implementations are expected to support the HTTP/1.1 protocol, the support of other protocols is
  * optional.
  * </p>
- *
- * @see DefaultSchemaClient
  */
 @FunctionalInterface
 public interface SchemaClient extends Function<String, InputStream> {

core/src/main/java/org/everit/json/schema/loader/SchemaLoader.java

@@ -101,6 +101,7 @@ public static Schema load(final JSONObject schemaJson) {
    *          the JSON representation of the schema.
    * @param httpClient
    *          the HTTP client to be used for resolving remote JSON references.
+   * @return the created schema
    */
   public static Schema load(final JSONObject schemaJson, final SchemaClient httpClient) {
     String schemaId = schemaJson.optString("id");
@@ -455,8 +456,12 @@ private <E> void ifPresent(final String key, final Class<E> expectedType,
 
   /**
    * Populates a {@code Schema.Builder} instance from the {@code schemaJson} schema definition.
+   *
+   * @return the builder which already contains the validation criteria of the schema, therefore
+   *         {@link Schema.Builder#build()} can be immediately used to acquire the {@link Schema}
+   *         instance to be used for validation
    */
-  public Schema.Builder<?> load() {
+  private Schema.Builder<?> load() {
     Schema.Builder<?> builder;
     if (schemaJson.has("enum")) {
       builder = buildEnumSchema();

core/src/main/java/org/everit/json/schema/loader/internal/JSONPointer.java

@@ -109,8 +109,16 @@ public static final JSONPointer forDocument(final JSONObject document, final Str
 
   /**
    * Static factory method.
+   *
+   * @param schemaClient
+   *          the client implementation to be used for obtaining the remote raw JSON schema
+   * @param url
+   *          a complete URL (including protocol definition like "http://"). It may also contain a
+   *          fragment
+   * @return a JSONPointer instance with a document provider created for the URL and the optional
+   *         fragment specified by the {@code url}
    */
-  public static final JSONPointer forURL(final SchemaClient httpClient, final String url) {
+  public static final JSONPointer forURL(final SchemaClient schemaClient, final String url) {
     int poundIdx = url.indexOf('#');
     String fragment;
     String toBeQueried;
@@ -121,7 +129,7 @@ public static final JSONPointer forURL(final SchemaClient httpClient, final Stri
       fragment = url.substring(poundIdx);
       toBeQueried = url.substring(0, poundIdx);
     }
-    return new JSONPointer(() -> executeWith(httpClient, toBeQueried), fragment);
+    return new JSONPointer(() -> executeWith(schemaClient, toBeQueried), fragment);
   }
 
   private final Supplier<JSONObject> documentProvider;