📝 Add docstrings to date-handler

Docstrings generation was requested by @bageshwar.

* #11 (comment)

The following files were modified:

* `pibify-core/src/main/java/com/flipkart/pibify/codegen/stub/AbstractPibifyHandlerCache.java`
* `pibify-core/src/main/java/com/flipkart/pibify/codegen/stub/DateHandler.java`
* `pibify-maven-plugin/src/test/java/com/flipkart/pibify/codegen/BeanIntrospectorBasedCodeGenSpecCreatorTest.java`
* `pibify-maven-plugin/src/test/java/com/flipkart/pibify/codegen/CodeGeneratorImplTest.java`
* `pibify-maven-plugin/src/test/java/com/flipkart/pibify/test/data/ClassWithReferences.java`

pibify-core/src/main/java/com/flipkart/pibify/codegen/stub/AbstractPibifyHandlerCache.java

@@ -56,6 +56,27 @@ public abstract class AbstractPibifyHandlerCache {
 
     protected Map<Class<?>, PibifyGenerated<?>> cache;
 
+    /**
+     * Initializes the handler cache by registering handlers for various data types.
+     *
+     * This constructor populates the {@code mapBuilder} with default handlers for:
+     * <ul>
+     *   <li>Base object types: {@code Object}</li>
+     *   <li>Map implementations: {@code Map}, {@code HashMap}, {@code TreeMap}, {@code LinkedHashMap}</li>
+     *   <li>Collection implementations: {@code ArrayList}, {@code Vector}, {@code ArrayDeque}, {@code Stack}</li>
+     *   <li>Set implementations: {@code HashSet}, {@code TreeSet}, {@code LinkedHashSet}</li>
+     *   <li>Special types: {@code BigDecimal}, {@code Date}, {@code SerializationContext}</li>
+     * </ul>
+     *
+     * Each type is associated with an appropriate handler to manage serialization and deserialization.
+     *
+     * @see PibifyObjectHandler
+     * @see PibifyMapHandler
+     * @see PibifyCollectionHandler
+     * @see BigDecimalHandler
+     * @see DateHandler
+     * @see SerializationContextHandler
+     */
     protected AbstractPibifyHandlerCache() {
         mapBuilder.put(Object.class, new PibifyObjectHandler(this));
 
@@ -80,6 +101,13 @@ protected AbstractPibifyHandlerCache() {
         mapBuilder.put(SerializationContext.class, new SerializationContextHandler());
     }
 
+    /**
+     * Builds the handler cache map with optional duplicate handling behavior.
+     *
+     * @param throwIfDuplicates Determines the strategy for handling duplicate keys during map construction
+     *                           - If true, throws an exception when duplicate keys are encountered
+     *                           - If false, keeps the last encountered value for duplicate keys
+     */
     protected void packMap(boolean throwIfDuplicates) {
         if (throwIfDuplicates) {
             cache = mapBuilder.buildOrThrow();

pibify-core/src/main/java/com/flipkart/pibify/codegen/stub/DateHandler.java

@@ -32,6 +32,15 @@
  */
 public class DateHandler extends PibifyGenerated<Date> {
 
+    /**
+     * Serializes a Date object to a long representation of milliseconds since epoch.
+     *
+     * @param object The Date object to be serialized, can be null
+     * @param serializer The serializer used to write the Date's time value
+     * @param context The serialization context (unused in this implementation)
+     * @throws PibifyCodeExecException if serialization encounters an unexpected error
+     * @throws RuntimeException if an IOException occurs during serialization
+     */
     @Override
     public void serialize(Date object, ISerializer serializer, SerializationContext context) throws PibifyCodeExecException {
         if (object != null) {
@@ -43,6 +52,15 @@ public void serialize(Date object, ISerializer serializer, SerializationContext
         }
     }
 
+    /**
+     * Deserializes a Date object from the provided deserializer.
+     *
+     * @param deserializer The deserializer used to read the Date object
+     * @param type The target Date class type
+     * @param context The serialization context for deserialization
+     * @return A Date object reconstructed from the serialized data, or null if no valid date was found
+     * @throws PibifyCodeExecException If an I/O error occurs during deserialization
+     */
     @Override
     public Date deserialize(IDeserializer deserializer, Class<Date> type, SerializationContext context) throws PibifyCodeExecException {
         try {

pibify-maven-plugin/src/test/java/com/flipkart/pibify/codegen/BeanIntrospectorBasedCodeGenSpecCreatorTest.java

@@ -319,6 +319,20 @@ public void createClassWithNativeCollections() throws CodeGenException {
 
     }
 
+    /**
+     * Tests the creation of a code generation specification for a class with reference fields.
+     *
+     * This test method validates the introspection and specification generation for a class containing
+     * reference fields, including a Date object, a string, and a reference to another class.
+     *
+     * @throws CodeGenException if an error occurs during code generation specification creation
+     *
+     * Verifies the following aspects of the generated specification:
+     * - Correct number of fields (3)
+     * - Detailed field specifications for 'date', 'aString', and 'reference'
+     * - Correct field names, getters, setters, indices, and data types
+     * - Nested field validation for the referenced class
+     */
     @Test
     public void createClassWithReference() throws CodeGenException {
         BeanIntrospectorBasedCodeGenSpecCreator creator = new BeanIntrospectorBasedCodeGenSpecCreator();

pibify-maven-plugin/src/test/java/com/flipkart/pibify/codegen/CodeGeneratorImplTest.java

@@ -292,6 +292,22 @@ public void testClassWithNativeCollections() throws Exception {
         assertArrayEquals(testPayload.getListOfBytes().get(1), deserialized.getListOfBytes().get(1));
     }
 
+    /**
+     * Tests serialization and deserialization of a class with references to other classes.
+     *
+     * This test method verifies that a class containing references to another class can be correctly
+     * serialized and deserialized while maintaining the integrity of its nested object structure.
+     *
+     * The test performs the following steps:
+     * 1. Creates a code generation specification using bean introspection
+     * 2. Generates Java code for the class with references
+     * 3. Creates a test payload with randomized data
+     * 4. Compiles the generated code
+     * 5. Serializes and deserializes the payload
+     * 6. Asserts that the deserialized object is equal to the original payload
+     *
+     * @throws Exception if any error occurs during code generation, compilation, or serialization
+     */
     @Test
     public void testClassWithReferences() throws Exception {
         BeanIntrospectorBasedCodeGenSpecCreator creator = new BeanIntrospectorBasedCodeGenSpecCreator();
@@ -316,6 +332,23 @@ public void testClassWithReferences() throws Exception {
         assertEquals(testPayload, deserialized);
     }
 
+    /**
+     * Tests serialization and deserialization of a class containing collections of objects.
+     *
+     * This test method verifies that a class with various object collections can be correctly
+     * serialized and deserialized, maintaining the integrity of different collection types
+     * including lists, maps, and arrays of objects.
+     *
+     * The test performs the following steps:
+     * 1. Creates a code generation specification for ClassWithObjectCollections
+     * 2. Generates Java code for serialization/deserialization
+     * 3. Randomizes test payload data
+     * 4. Compiles dependent classes
+     * 5. Invokes generated serialization/deserialization code
+     * 6. Compares original and deserialized objects across multiple collection types
+     *
+     * @throws Exception if any error occurs during code generation, compilation, or serialization
+     */
     @Test
     public void testClassWithObjectCollections() throws Exception {
         BeanIntrospectorBasedCodeGenSpecCreator creator = new BeanIntrospectorBasedCodeGenSpecCreator();

pibify-maven-plugin/src/test/java/com/flipkart/pibify/test/data/ClassWithReferences.java

@@ -40,6 +40,12 @@ public class ClassWithReferences {
     @Pibify(3)
     private Date date;
 
+    /**
+     * Randomizes the current instance of ClassWithReferences by setting its properties to random or current values.
+     *
+     * @return the current instance with randomized properties
+     * @see AnotherClassWithNativeCollections#randomize()
+     */
     public ClassWithReferences randomize() {
         aString = "str" + Math.random();
         date = new Date(System.currentTimeMillis());
@@ -60,25 +66,56 @@ public String getaString() {
         return aString;
     }
 
+    /**
+     * Sets the string value for this instance.
+     *
+     * @param aString the string to be assigned to the {@code aString} field
+     */
     public void setaString(String aString) {
         this.aString = aString;
     }
 
+    /**
+     * Retrieves the current date associated with this instance.
+     *
+     * @return the Date object representing the date of this instance
+     */
     public Date getDate() {
         return date;
     }
 
+    /**
+     * Sets the date for this instance of ClassWithReferences.
+     *
+     * @param date the Date object to be assigned to this instance's date field
+     */
     public void setDate(Date date) {
         this.date = date;
     }
 
+    /**
+     * Compares this {@code ClassWithReferences} instance with another object for equality.
+     *
+     * @param o the object to compare with this instance
+     * @return {@code true} if the objects are equal, {@code false} otherwise
+     *
+     * Two {@code ClassWithReferences} instances are considered equal if they have:
+     * - The same reference object
+     * - The same string value
+     * - The same date
+     */
     @Override
     public boolean equals(Object o) {
         if (!(o instanceof ClassWithReferences)) return false;
         ClassWithReferences that = (ClassWithReferences) o;
         return Objects.equals(reference, that.reference) && Objects.equals(aString, that.aString) && Objects.equals(date, that.date);
     }
 
+    /**
+     * Generates a hash code for the current instance based on its reference, string, and date fields.
+     *
+     * @return an integer hash code that combines the hash values of the reference, aString, and date fields
+     */
     @Override
     public int hashCode() {
         return Objects.hash(reference, aString, date);