Documentation in english and nested value in collections mapping.

Author: jonpereiradev

src/main/java/com/github/jonpereiradev/diffobjects/DiffException.java

@@ -1,5 +1,10 @@
 package com.github.jonpereiradev.diffobjects;
 
+/**
+ * Exception for any generic error found in the diff execution.
+ *
+ * @author jonpereiradev@gmail.com
+ */
 public class DiffException extends RuntimeException {
 
     public DiffException(String message) {

src/main/java/com/github/jonpereiradev/diffobjects/DiffObjects.java

@@ -3,24 +3,32 @@
 import com.github.jonpereiradev.diffobjects.builder.DiffConfiguration;
 import com.github.jonpereiradev.diffobjects.strategy.DiffMetadata;
 import com.github.jonpereiradev.diffobjects.strategy.DiffReflections;
+import com.github.jonpereiradev.diffobjects.strategy.DiffStrategy;
+import java.util.ArrayList;
 
 import java.util.Collections;
-import java.util.LinkedList;
 import java.util.List;
 import java.util.Objects;
 
 /**
+ * Responsible for execute the diff between two objects.
+ *
  * @author jonpereiradev@gmail.com
  */
 public final class DiffObjects {
 
+    private DiffObjects() {
+        throw new UnsupportedOperationException("No need to create an instance of this class.");
+    }
+
     /**
-     * Executa o instance entre o antes e o depois.
+     * Execute the diff between two objects using annotations.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informaçnoes depois da alteração.
-     * @return resultado do instance.
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     *
+     * @return a list with the results of the diff.
      */
     public static <T> List<DiffResult> diff(T beforeState, T afterState) {
         Objects.requireNonNull(beforeState, "Before state is required.");
@@ -30,59 +38,69 @@ public static <T> List<DiffResult> diff(T beforeState, T afterState) {
     }
 
     /**
-     * Verifica se os objetos são iguais no instance.
+     * Execute the diff between two objects using a configuration.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informações depois da alteração.
-     * @return resultado do instance.
-     */
-    public static <T> boolean isEquals(T beforeState, T afterState) {
-        Objects.requireNonNull(beforeState, "Before state is required.");
-        Objects.requireNonNull(afterState, "After state is required.");
-
-        return isEquals(beforeState, afterState, DiffReflections.mapAnnotations(beforeState.getClass()));
-    }
-
-    /**
-     * Executa o instance entre o antes e o depois.
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     * @param configuration the configuration of the diff.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informaçnoes depois da alteração.
-     * @return resultado do instance.
+     * @return a list with the results of the diff.
      */
     public static <T> List<DiffResult> diff(T beforeState, T afterState, DiffConfiguration configuration) {
         Objects.requireNonNull(beforeState, "Before state is required.");
         Objects.requireNonNull(afterState, "After state is required.");
         Objects.requireNonNull(configuration, "Configuration is required.");
 
-        List<DiffResult> results = new LinkedList<>();
+        List<DiffMetadata> metadatas = configuration.build();
+        List<DiffResult> results = new ArrayList<>(metadatas.size());
+
+        for (DiffMetadata metadata : metadatas) {
+            DiffStrategy strategy = metadata.getStrategy();
+            DiffResult diff = strategy.diff(beforeState, afterState, metadata);
 
-        for (DiffMetadata metadata : configuration.build()) {
-            DiffResult diff = metadata.getStrategy().diff(beforeState, afterState, metadata);
             diff.setProperties(Collections.unmodifiableMap(metadata.getProperties()));
+
             results.add(diff);
         }
 
         return results;
     }
 
     /**
-     * Verifica se os objetos são iguais no instance.
+     * Check if exists any difference between the two objects using annotations.
+     *
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     *
+     * @return {@code true} if no difference exists between the objects or {@code false} otherwise.
+     */
+    public static <T> boolean isEquals(T beforeState, T afterState) {
+        Objects.requireNonNull(beforeState, "Before state is required.");
+        Objects.requireNonNull(afterState, "After state is required.");
+
+        return isEquals(beforeState, afterState, DiffReflections.mapAnnotations(beforeState.getClass()));
+    }
+
+    /**
+     * Check if exists any difference between the two objects.
+     *
+     * @param <T> type of object been compared.
+     * @param beforeState the before object state to compare with after object.
+     * @param afterState the after object state to compare with befor object.
+     * @param configuration the configuration of the diff.
      *
-     * @param <T>         tipo do objeto comparado.
-     * @param beforeState objeto com as informações antes da alteração.
-     * @param afterState  objeto com as informações depois da alteração.
-     * @return resultado do instance.
+     * @return {@code true} if no difference exists between the objects or {@code false} otherwise.
      */
     public static <T> boolean isEquals(T beforeState, T afterState, DiffConfiguration configuration) {
         Objects.requireNonNull(beforeState, "Before state is required.");
         Objects.requireNonNull(afterState, "After state is required.");
         Objects.requireNonNull(configuration, "Configuration is required.");
 
         for (DiffMetadata metadata : configuration.build()) {
-            DiffResult result = metadata.getStrategy().diff(beforeState, afterState, metadata);
+            DiffStrategy strategy = metadata.getStrategy();
+            DiffResult result = strategy.diff(beforeState, afterState, metadata);
 
             if (!result.isEquals()) {
                 return false;

src/main/java/com/github/jonpereiradev/diffobjects/DiffResult.java

@@ -3,13 +3,15 @@
 import java.util.Map;
 
 /**
+ * Result of a diff with the before and after state.
+ *
  * @author jonpereiradev@gmail.com
  */
-public class DiffResult {
+public final class DiffResult {
 
-    private Object before;
-    private Object after;
-    private boolean equals;
+    private final Object before;
+    private final Object after;
+    private final boolean equals;
     private Map<String, String> properties;
 
     public DiffResult(Object before, Object after, boolean equals) {
@@ -34,7 +36,7 @@ public Map<String, String> getProperties() {
         return properties;
     }
 
-    public void setProperties(Map<String, String> properties) {
+    void setProperties(Map<String, String> properties) {
         this.properties = properties;
     }
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffMapping.java

@@ -6,23 +6,23 @@
 import java.lang.annotation.Target;
 
 /**
- * <p>A property or object annotated with this will be checked for difference between two objects.</p>
- * <p>When annotated on a object without value(), the equals method of this object will be executed.</p>
- * <p>When annotated on a object with value(), the property will be evaluated for equality.</p>
+ * <p>A method annotated with this will be checked for difference between two objects.</p>
+ * <p>When annotated on a method without value(), the equals method of this object will be executed.</p>
+ * <p>When annotated on a method with value(), the property will be evaluated for equality.</p>
  *
  * @author jonpereiradev@gmail.com
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.METHOD, ElementType.TYPE})
+@Target({ElementType.METHOD})
 public @interface DiffMapping {
 
     /**
-     * Defines the property that will be evaluated for equality. It can be nested property like user.address.id.
+     * @return Defines the property that will be evaluated for equality. It can be nested property like user.address.id.
      */
     String value() default "";
 
     /**
-     * Aditional properties that will be on result for identification.
+     * @return Aditional properties that will be on the diff result object.
      */
     DiffProperty[] properties() default {};
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffMappings.java

@@ -6,12 +6,17 @@
 import java.lang.annotation.Target;
 
 /**
+ * Annotation to group multiple mappings on a method or to enable all methods if is used on a class.
+ *
  * @author jonpereiradev@gmail.com
  */
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.FIELD, ElementType.METHOD})
+@Target({ElementType.METHOD, ElementType.TYPE})
 public @interface DiffMappings {
 
-    DiffMapping[] value();
+    /**
+     * @return a group of mappings to make multiple diffs on a single method.
+     */
+    DiffMapping[] value() default {};
 
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffOrder.java

@@ -6,13 +6,17 @@
 import java.lang.annotation.Target;
 
 /**
+ * Defines an order for the method if necessary.
+ *
  * @author jonpereiradev@gmail.com
- * @see <a href="#">https://github.com/jonpereiradev/diff-objects</a>
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.FIELD, ElementType.METHOD})
 public @interface DiffOrder {
 
+    /**
+     * @return a number order for the method.
+     */
     int value();
 
 }

src/main/java/com/github/jonpereiradev/diffobjects/annotation/DiffProperty.java

@@ -15,12 +15,12 @@
 public @interface DiffProperty {
 
     /**
-     * Identifier of the property.
+     * @return identifier of the property.
      */
     String key();
 
     /**
-     * Value of the property.
+     * @return value of the property.
      */
     String value();
 

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffConfigurationImpl.java

@@ -8,6 +8,13 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Responsible for generate the configuration of the instance.
+ *
+ * @see DiffBuilder
+ * @see DiffInstanceBuilder
+ * @see DiffMappingBuilder
+ */
 final class DiffConfigurationImpl implements DiffConfiguration {
 
     private final Map<String, DiffMetadata> metadatas;

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffInstanceBuilder.java

@@ -4,6 +4,7 @@
  * Builder with the methods of a instance instance.
  *
  * @author jonpereiradev@gmail.com
+ * 
  * @see DiffBuilder
  * @see DiffMappingBuilder
  * @see DiffConfiguration
@@ -33,4 +34,3 @@ public interface DiffInstanceBuilder {
     DiffConfiguration configuration();
 
 }
-

src/main/java/com/github/jonpereiradev/diffobjects/builder/DiffMappingBuilder.java

@@ -4,6 +4,7 @@
  * Builder responsible for mapping the fields of a class to create a configuration of diff.
  *
  * @author jonpereiradev@gmail.com
+ *
  * @see DiffBuilder
  * @see DiffInstanceBuilder
  * @see DiffConfiguration
@@ -28,6 +29,7 @@ public interface DiffMappingBuilder {
      * Maps the getter of the field for the class.
      *
      * @param field name of the field that will me used to find the getter method.
+     *
      * @return the instance of this mapping.
      */
     DiffQueryBuilder mapping(String field);
@@ -37,6 +39,7 @@ public interface DiffMappingBuilder {
      *
      * @param field name of the field that will me used to find the getter method.
      * @param value the nested property of the object to make the diff.
+     *
      * @return the instance of this mapping.
      */
     DiffQueryBuilder mapping(String field, String value);
@@ -45,9 +48,9 @@ public interface DiffMappingBuilder {
      * Remove a mapping of the field for the class.
      *
      * @param field name of the field that will me used to remove.
+     *
      * @return the instance of this mapping.
      */
     DiffMappingBuilder unmapping(String field);
 
 }
-