Added some more class level documentation

Author: langecode

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Curie.java

@@ -7,7 +7,9 @@
 
 /**
  * Annotation specifying a CURIE for use with links. As defined by W3C in
- * <a href="https://www.w3.org/TR/2010/NOTE-curie-20101216/">CURIE Syntax 1.0</a>.
+ * <a href="https://www.w3.org/TR/2010/NOTE-curie-20101216/">CURIE Syntax 1.0</a>. Note that in
+ * the context of HAL the only substitution done to the template URI of a curie is the
+ * <code>{rel}</code> place holder.
  */
 @Target({ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Curies.java

@@ -6,7 +6,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Annotation specifying a CURIE for use with links
+ * Annotation specifying an array of curies to be used in defining link relations.
  */
 @Target({ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/io/openapitools/jackson/dataformat/hal/annotation/Link.java

@@ -18,7 +18,7 @@
     String value() default "";
 
     /**
-     * CURIE name - if not set then no CURIE will be associated.
+     * CURIE prefix - if not set then no CURIE will be associated.
      * @return name of the CURIE intended to be used with this link.
      */
     String curie() default "";

src/main/java/io/openapitools/jackson/dataformat/hal/deser/HALBeanDeserializer.java

@@ -19,7 +19,9 @@
 import java.util.stream.StreamSupport;
 
 /**
- * Deserializer to handle incoming application/hal+json.
+ * Deserializer to handle incoming application/hal+json. The de-serializer is responsible for intercepting
+ * the reserved properties (<code>_links</code> and <code>_embedded</code>) and mapping the properties of these
+ * objects in the incoming json to the uniquely assigned properties of the POJO class.
  */
 public class HALBeanDeserializer extends DelegatingDeserializer {
 
@@ -28,7 +30,7 @@ public HALBeanDeserializer(BeanDeserializerBase delegate) {
     }
 
     @Override
-    public Object deserialize(JsonParser p, DeserializationContext ctxt) throws IOException, JsonProcessingException {
+    public Object deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
         TreeNode tn = p.getCodec().readTree(p);
         if (tn.isObject()) {
             ObjectNode root = (ObjectNode) tn;

src/main/java/io/openapitools/jackson/dataformat/hal/deser/HALBeanDeserializerModifier.java

@@ -17,7 +17,8 @@
 
 /**
  * Modify the deserialization of classes annotated with {@link Resource}. Deserialization will handle the reserved
- * properties <code>_links</code> and <code>_embedded</code>.
+ * properties <code>_links</code> and <code>_embedded</code> by assigning a unique property name to each of the
+ * properties that are part of these sections.
  */
 public class HALBeanDeserializerModifier extends BeanDeserializerModifier {
 

src/main/java/io/openapitools/jackson/dataformat/hal/deser/ReservedProperty.java

@@ -37,6 +37,14 @@ public String getPropertyName() {
         return name;
     }
 
+    /**
+     * Assign an alternate name to POJO property that is unique outside of the the reserved
+     * object - if it is a link or embedded property.
+     *
+     * @param bpd The property to process.
+     * @param map Curie map applying to properties of <code>_links</code> section.
+     * @return An alternate name if relevant otherwise the original name is maintained.
+     */
     public String alternateName(BeanPropertyDefinition bpd, CurieMap map) {
         String originalName = bpd.getName();
 
@@ -69,6 +77,13 @@ public String alternateName(BeanPropertyDefinition bpd, CurieMap map) {
         return alternateName(name);
     }
 
+    /**
+     * Given a property that should belong to this reserved object instance a name is assigned which will
+     * be unique outside of the reserved property.
+     *
+     * @param originalName Property name within this reserved object that should be unique outside.
+     * @return Alternate name for the given original name.
+     */
     public String alternateName(String originalName) {
         return prefix.toString() + ":" + originalName;
     }