Merge pull request #51 from CJSCommonPlatform/javadoc

add javadoc to classes
CJSCommonPlatform · Sep 12, 2017 · f27a09c · f27a09c
2 parents 40fe137 + 18c1d3a
commit f27a09c
Show file tree

Hide file tree

Showing 13 changed files with 230 additions and 11 deletions.
diff --git a/...src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java b/...src/main/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProvider.java
@@ -2,15 +2,15 @@
 
 import static java.util.Arrays.asList;
 
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGeneratorFactory;
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin;
-import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportUuidsPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportZonedDateTimePlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;
 
 import java.util.List;
 

diff --git a/...ce/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java b/...ce/generation/pojo/generators/plugin/classgenerator/AddFieldsAndMethodsToClassPlugin.java
@@ -19,6 +19,15 @@
 import com.squareup.javapoet.ParameterSpec;
 import com.squareup.javapoet.TypeSpec;
 
+/**
+ * Plugin that adds fields, a constructor and getter methods to a class's
+ * Type Specification.
+ *
+ * Without this plugin each class will be generated with
+ * no fields nor getter methods and with an empty constructor. For this reason
+ * this class is added by default; although it is possible to override it should
+ * you need to change it's behaviour.
+ */
 public class AddFieldsAndMethodsToClassPlugin implements ClassModifyingPlugin {
 
     private final AdditionalPropertiesGenerator additionalPropertiesGenerator = new AdditionalPropertiesGenerator();

diff --git a/...uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java b/...uk/gov/justice/generation/pojo/generators/plugin/classgenerator/ClassModifyingPlugin.java
@@ -4,8 +4,25 @@
 
 import com.squareup.javapoet.TypeSpec;
 
+/**
+ * Interface for all plugins that modify the generated classes. These can be plugins for
+ * example, adding fields and methods to the class, making the class {@link java.io.Serializable},
+ * or adding specific annotations to the class or it's methods.
+ *
+ * {@link MakeClassSerializablePlugin}
+ * {@link AddFieldsAndMethodsToClassPlugin}
+ */
 public interface ClassModifyingPlugin {
 
+    /**
+     * Modifies the generation of a class.
+     *
+     * @param typeSpecBuilder A builder for generating the class
+     * @param classDefinition The definition of the class from the json schema document
+     * @param pluginContext Access to any data the plugin might need
+     *
+     * @return The modified class's {@link TypeSpec} builder
+     */
     TypeSpec.Builder generateWith(final TypeSpec.Builder typeSpecBuilder,
                                   final ClassDefinition classDefinition,
                                   final PluginContext pluginContext);

diff --git a/...stice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java b/...stice/generation/pojo/generators/plugin/classgenerator/GenerateBuilderForClassPlugin.java
@@ -1,14 +1,50 @@
 package uk.gov.justice.generation.pojo.generators.plugin.classgenerator;
 
 import uk.gov.justice.generation.pojo.dom.ClassDefinition;
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.PluginContext;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGenerator;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.builder.BuilderGeneratorFactory;
 
 import com.squareup.javapoet.MethodSpec;
 import com.squareup.javapoet.TypeSpec;
 
+/**
+ * Adds a builder for the class as an static inner class and a static
+ * method for accessing the builder. For example, a class <i>MyClass</i> specified
+ * with one property <i>myProperty</i> would be generated thusly:
+ *
+ * <pre>
+ *     {@code public class MyClass {
+ *
+ *          private final String myProperty;
+ *
+ *          public MyClass(final String myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public String getMyProperty() {
+ *              return myProperty;
+ *          }
+ *
+ *          public static Builder myClass() {
+ *              return new MyClass.Builder();
+ *          }
+ *
+ *          public static class Builder {
+ *
+ *              private String myProperty;
+ *
+ *              public Builder withMyProperty(final String myProperty) {
+ *                  this.myProperty = myProperty;
+ *                  return this;
+ *              }
+ *
+ *              public MyClass build() {
+ *                  return new MyClass(myProperty);
+ *              }
+ *          }
+ *      }
+ * }</pre>
+ */
 public class GenerateBuilderForClassPlugin implements ClassModifyingPlugin {
 
     private final BuilderGeneratorFactory builderGeneratorFactory;

diff --git a/...justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java b/...justice/generation/pojo/generators/plugin/classgenerator/MakeClassSerializablePlugin.java
@@ -12,6 +12,33 @@
 import com.squareup.javapoet.FieldSpec;
 import com.squareup.javapoet.TypeSpec;
 
+/**
+ * A class plugin that adds {@see Serializable} interface and
+ * {@Code serialVersionUID} to the generated class.
+ *
+ * Note: the serialVersionUID is always set to 1.
+ *
+ * For example:
+ *
+ * <pre>
+ *     {@code public class MyClass implements Serializable {
+ *
+ *          private static final long serialVersionUID = 1L;
+ *
+ *          private final String myProperty;
+ *
+ *          public MyClass(final String myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public String getMyProperty() {
+ *              return myProperty;
+ *          }
+ *      }
+ *     }
+ *
+ * </pre>
+ */
 public class MakeClassSerializablePlugin implements ClassModifyingPlugin {
 
     private static final String SERIAL_VERSION_FIELD_NAME = "serialVersionUID";

diff --git a/...uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java b/...uk/gov/justice/generation/pojo/generators/plugin/typename/SupportJavaOptionalsPlugin.java
@@ -10,6 +10,28 @@
 import com.squareup.javapoet.ParameterizedTypeName;
 import com.squareup.javapoet.TypeName;
 
+/**
+ * A type modifying plugin for setting all properties which are not marked as <i>required</i>
+ * in the json schema document to be wrapped in a java {@see Optional}.
+ *
+ * For example:
+ *
+ * <pre>
+ *     {@code public class MyClass {
+ *
+ *          private final Optional<String> myProperty;
+ *
+ *          public MyClass(final Optional<String> myProperty) {
+ *              this.myProperty = myProperty;
+ *          }
+ *
+ *          public Optional<String> getMyProperty() {
+ *              return myProperty;
+ *          }
+ *      }
+ *
+ * }</pre>
+ */
 public class SupportJavaOptionalsPlugin implements TypeModifyingPlugin {
 
     @Override

diff --git a/...in/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java b/...in/java/uk/gov/justice/generation/pojo/generators/plugin/typename/SupportUuidsPlugin.java
@@ -10,6 +10,50 @@
 
 import com.squareup.javapoet.TypeName;
 
+/**
+ * Adds support for using {@see UUID} as return types and constructor parameters in the generated
+ * class.
+ *
+ * To Use:
+ * <p>
+ *     The uuid should be specified as a reference in your json schema file:
+ *     <pre>
+ *         {@code "myProperty": {
+ *                  "$ref": "#/definitions/UUID"
+ *              },
+ *              "definitions": {
+ *                  "UUID": {
+ *                      "type": "string",
+ *                      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$",
+ *                  }
+ *              }
+ *
+ *     }</pre>
+ * </p>
+ *
+ * The name {@code UUID} in the definition is important as this is how we specify that
+ * the types should be of type {@link UUID}.
+ *
+ * <p>
+ *      This will generate the following code:
+ *      <pre>
+ *          {@code
+ *  public class MyClass {
+ *
+ *                  private final UUID myProperty;
+ *
+ *                  public MyClass(final UUID myProperty) {
+ *                      this.myProperty = myProperty;
+ *                  }
+ *
+ *                  public UUID getMyProperty() {
+ *                      return myProperty;
+ *                  }
+ *              }
+ * }</pre>
+ * </p>
+ *
+ */
 public class SupportUuidsPlugin implements TypeModifyingPlugin {
 
     @Override

diff --git a/...uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java b/...uk/gov/justice/generation/pojo/generators/plugin/typename/SupportZonedDateTimePlugin.java
@@ -10,6 +10,50 @@
 
 import com.squareup.javapoet.TypeName;
 
+/**
+ * Adds support for using {@see ZonedDateTime} as return types and constructor parameters in the generated
+ * class.
+ *
+ * To Use:
+ * <p>
+ *     The ZonedDateTime should be specified as a reference in your json schema file:
+ *     <pre>
+ *         {@code "myProperty": {
+ *                  "$ref": "#/definitions/ZonedDateTime"
+ *              },
+ *              "definitions": {
+ *                  "ZonedDateTime": {
+ *                      "type": "string",
+ *                      "pattern": "^[1|2][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]$"
+ *                  }
+ *              }
+ *
+ *     }</pre>
+ * </p>
+ *
+ * The name {@code ZonedDateTime} in the definition is important as this is how we specify that
+ * the types should be of type {@link ZonedDateTime}.
+ *
+ * <p>
+ *      This will generate the following code:
+ *      <pre>
+ *          {@code public class MyClass {
+ *
+ *                  private final ZonedDateTime myProperty;
+ *
+ *                  public MyClass(final ZonedDateTime myProperty) {
+ *                      this.myProperty = myProperty;
+ *                  }
+ *
+ *                  public ZonedDateTime getMyProperty() {
+ *                      return myProperty;
+ *                  }
+ *              }
+ * }</pre>
+ * </p>
+ *
+ */
+
 public class SupportZonedDateTimePlugin implements TypeModifyingPlugin {
 
     @Override

diff --git a/...n/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java b/...n/java/uk/gov/justice/generation/pojo/generators/plugin/typename/TypeModifyingPlugin.java
@@ -4,7 +4,27 @@
 
 import com.squareup.javapoet.TypeName;
 
+/**
+ * Interface for all plugins that modify return types and parameters of generated classes. For
+ * example these plugins can change the types of nullable properties in a class to
+ * {@link java.util.Optional}, support for {@link java.util.UUID} as return types and constructor
+ * parameters, or support for {@link java.time.ZonedDateTime} as return types and constructor
+ * parameters
+ *
+ * {@link SupportJavaOptionalsPlugin}
+ * {@link SupportUuidsPlugin}
+ * {@link SupportZonedDateTimePlugin}
+ */
 public interface TypeModifyingPlugin {
 
+    /**
+     * Modifies the TypeName (used as constructor parameters and getter return types) of
+     * generated classes in some way.
+     *
+     * @param typeName The type name to be modified
+     * @param definition The FieldDefinition of the type to be modified
+     *
+     * @return The modified type name
+     */
     TypeName modifyTypeName(final TypeName typeName, final Definition definition);
 }
diff --git a/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java b/pojo-generator-core/src/test/java/uk/gov/justice/generation/pojo/TestPluginProvider.java
@@ -4,8 +4,8 @@
 import static java.util.Collections.singletonList;
 
 import uk.gov.justice.generation.pojo.generators.plugin.PluginProvider;
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;

diff --git a/...test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java b/...test/java/uk/gov/justice/generation/pojo/generators/plugin/DefaultPluginProviderTest.java
@@ -5,14 +5,14 @@
 import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin;
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.GenerateBuilderForClassPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportJavaOptionalsPlugin;
-import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportUuidsPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.SupportZonedDateTimePlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;
 
 import java.util.List;
 

diff --git a/...er/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java b/...er/src/main/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProvider.java
@@ -3,9 +3,9 @@
 import static java.util.Arrays.asList;
 import static java.util.Collections.emptyList;
 
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddEventAnnotationToClassPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;
 

diff --git a/...rc/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java b/...rc/test/java/uk/gov/justice/generation/pojo/generators/plugin/PluginTestProviderTest.java
@@ -5,9 +5,9 @@
 import static org.hamcrest.CoreMatchers.is;
 import static org.junit.Assert.assertThat;
 
-import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddEventAnnotationToClassPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.AddFieldsAndMethodsToClassPlugin;
+import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.ClassModifyingPlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.classgenerator.MakeClassSerializablePlugin;
 import uk.gov.justice.generation.pojo.generators.plugin.typename.TypeModifyingPlugin;