Improve javadoc for generated keys

Fix warnings about missing javadoc in Key classes
generated by ListKeyTemplate.xtend.

Add generation of javadoc for all values constructor,
getter methods and for the class.

JIRA: MDSAL-759
Change-Id: I1cef9d4b4415e0f786eca414937b1958d31acd38
Signed-off-by: Samuel Schneider <samuel.schneider@pantheon.tech>
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ListKeyTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ListKeyTemplate.xtend
index 0087e95aeb4e031ce0e91c33b8b7b850d4c226a0..14d92906eff9b2348098d34784d96527fa4d3a3e 100644 (file)
--- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ListKeyTemplate.xtend
+++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/ListKeyTemplate.xtend
@@ -8,7 +8,11 @@
 package org.opendaylight.mdsal.binding.java.api.generator
 
 import org.opendaylight.mdsal.binding.model.api.GeneratedProperty
+import org.opendaylight.mdsal.binding.model.api.GeneratedType
 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject
+import org.opendaylight.mdsal.binding.model.api.ParameterizedType;
+import org.opendaylight.mdsal.binding.model.api.Type
+import org.opendaylight.mdsal.binding.model.ri.BindingTypes
 
 /**
  * Template for generating JAVA class.
@@ -24,6 +28,14 @@ final class ListKeyTemplate extends ClassTemplate {
     }
 
     override allValuesConstructor() '''
+        /**
+         * Constructs an instance.
+         *
+         «FOR p : allProperties»
+            * @param «p.fieldName» the entity «p.getName»
+         «ENDFOR»
+         * @throws NullPointerException if any of the arguments are null
+         */
         public «type.name»(«allProperties.asNonNullArgumentsDeclaration») {
             «FOR p : allProperties»
                 «val fieldName = p.fieldName»
@@ -36,8 +48,39 @@ final class ListKeyTemplate extends ClassTemplate {
     '''
 
     override getterMethod(GeneratedProperty field) '''
+        /**
+         * Return «field.getName», guaranteed to be non-null.
+         *
+         * @return {@code «field.returnType.importedName»} «field.getName», guaranteed to be non-null.
+         */
         public «field.returnType.importedNonNull» «field.getterMethodName»() {
             return «field.fieldName»«field.cloneCall»;
         }
     '''
+
+    override protected String formatDataForJavaDoc(GeneratedType type) {
+        val listType = findListType(type)
+        if (listType === null) {
+            return ""
+        }
+
+        val importedName = listType.importedName
+        return '''
+            This class represents the key of {@link «importedName»} class.
+
+            @see «importedName»
+        '''
+    }
+
+    private static def Type findListType(GeneratedType type) {
+        for (Type implType : type.getImplements()) {
+            if (implType instanceof ParameterizedType) {
+                val identifiable = BindingTypes.extractIdentifiable(implType)
+                if (identifiable !== null) {
+                    return identifiable
+                }
+            }
+        }
+        return null
+    }
 }

diff --git a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/BindingTypes.java b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/BindingTypes.java
index 511a96adb9635da16858d26edf2410e15e3f77d7..f9e4b2a65a4b07286b1e5ce0b418d28498a48e7b 100644 (file)
--- a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/BindingTypes.java
+++ b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/BindingTypes.java
@@ -338,4 +338,25 @@ public final class BindingTypes {
         }
         return null;
     }
+
+    /**
+     * Return the {@link Identifiable} type a parameterized {@link Identifier} type references.
+     *
+     * @param type Parameterized type
+     * @return Identifiable target, or null if {@code type} does not match the result of {@link #identifier(Type)}
+     * @throws NullPointerException if {@code type} is null
+     */
+    @Beta
+    public static @Nullable Type extractIdentifiable(final ParameterizedType type) {
+        if (IDENTIFIER.equals(type.getRawType())) {
+            final var args = type.getActualTypeArguments();
+            if (args.length == 1) {
+                final var arg = args[0];
+                if (arg != null) {
+                    return arg;
+                }
+            }
+        }
+        return null;
+    }
 }