javadoc improvements

Author: erosb

core/src/main/java/org/everit/jsonvalidator/ArraySchema.java

@@ -24,16 +24,13 @@
 
 /**
  * Array schema validator.
- *
- * {@link http://json-schema.org/latest/json-schema-validation.html#anchor36 See the according
- * specification}.
  */
 public class ArraySchema extends Schema {
 
   /**
    * Builder class for {@link ArraySchema}.
    */
-  public static class Builder extends Schema.Builder {
+  public static class Builder extends Schema.Builder<ArraySchema> {
 
     private boolean requiresArray = true;
 

core/src/main/java/org/everit/jsonvalidator/CombinedSchema.java

@@ -21,15 +21,6 @@
 
 /**
  * Validator for {@code allOf}, {@code oneOf}, {@code anyOf} schemas.
- *
- * <p>
- * See the following paragraphs of the specification for more details:
- * <ul>
- * <li>{@link http://json-schema.org/latest/json-schema-validation.html#anchor82}</li>
- * <li>{@link http://json-schema.org/latest/json-schema-validation.html#anchor85}</li>
- * <li>{@link http://json-schema.org/latest/json-schema-validation.html#anchor88}</li>
- * </ul>
- * </p>
  */
 public class CombinedSchema extends Schema {
 

core/src/main/java/org/everit/jsonvalidator/EnumSchema.java

@@ -20,10 +20,8 @@
 import java.util.Set;
 
 /**
- * {@link Enum} schema validator.
+ * Enum schema validator.
  *
- * {@link http://json-schema.org/latest/json-schema-validation.html#anchor76 See the according
- * specification}.
  */
 public class EnumSchema extends Schema {
 

core/src/main/java/org/everit/jsonvalidator/NotSchema.java

@@ -19,9 +19,6 @@
 
 /**
  * {@code Not} schema validator.
- *
- * {@link http://json-schema.org/latest/json-schema-validation.html#anchor91 See the according
- * specification}.
  */
 public class NotSchema extends Schema {
 

core/src/main/java/org/everit/jsonvalidator/ReferenceSchema.java

@@ -16,8 +16,9 @@
 package org.everit.jsonvalidator;
 
 /**
- * This class is used by {@link org.everit.jsonvalidator.loader.SchemaLoader} to resolve references
- * to the root schema, during the construction of the schema.
+ * This class is used by {@link org.everit.jsonvalidator.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 {
 

core/src/main/java/org/everit/jsonvalidator/Schema.java

@@ -66,14 +66,19 @@ public Builder<S> id(final String id) {
   /**
    * Constructor.
    */
-  protected Schema(final Builder builder) {
+  protected Schema(final Builder<?> builder) {
     this.title = builder.title;
     this.description = builder.description;
     this.id = builder.id;
   }
 
   /**
-   * Validates.
+   * Performs the schema validation.
+   *
+   * @param subject
+   *          the object to be validated
+   * @throws ValidationException
+   *           if the {@code subject} is invalid against this schema.
    */
   public abstract void validate(final Object subject);
 

core/src/main/java/org/everit/jsonvalidator/StringSchema.java

@@ -19,9 +19,6 @@
 
 /**
  * {@code String} schema validator.
- *
- * {@link http://json-schema.org/latest/json-schema-validation.html#anchor25 See the according
- * specification}.
  */
 public class StringSchema extends Schema {
 

core/src/main/java/org/everit/jsonvalidator/package-info.java

@@ -0,0 +1,11 @@
+package org.everit.jsonvalidator;
+
+/**
+ * This package contains classes representing different kinds of JSON schema.
+ *
+ * <p>The base class for each schema-type implementation is the {@link org.everit.jsonvalidator.Schema} class. In most cases schema instances
+ * are created via {@link org.everit.jsonvalidator.loader.SchemaLoader#load(org.json.JSONObject)} invocations, although direct schema
+ * instantiations - therefore programmatic schema creation - is also possible.</p>
+ *
+ * <p>Every {@code Schema} subclass has its separate {@code Builder} class which permits the creation of schemas by chained method calls.
+ */