From d90d2cca7277c800925d250a5125b5505f78c446 Mon Sep 17 00:00:00 2001
From: Samuel Schneider <samuel.schneider@pantheon.tech>
Date: Mon, 11 Jul 2022 11:52:08 +0200
Subject: [PATCH] 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>
---
 .../java/api/generator/ListKeyTemplate.xtend  | 43 +++++++++++++++++++
 .../mdsal/binding/model/ri/BindingTypes.java  | 21 +++++++++
 2 files changed, 64 insertions(+)

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 0087e95aeb..14d92906ef 100644
--- 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 511a96adb9..f9e4b2a65a 100644
--- 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;
+    }
 }
-- 
2.36.6