Generate javadoc for augments

Fix warnings about missing javadoc in augment interfaces.

Add setting of YangSourceDefinition when building GeneratedType
corresponding to augments so JavaFileTemplate.appendSnippet()
generate javadoc for this class.

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

diff --git a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractAugmentGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractAugmentGenerator.java
index d2ae1890aeff33390174153c72afe6d5b41fcd12..d48e841929b81ff106c8cc81729270e0f08b9099 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractAugmentGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractAugmentGenerator.java
@@ -20,6 +20,7 @@ import org.eclipse.jdt.annotation.NonNull;
 import org.opendaylight.mdsal.binding.generator.impl.reactor.CollisionDomain.Member;
 import org.opendaylight.mdsal.binding.generator.impl.rt.DefaultAugmentRuntimeType;
 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
+import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition;
 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilder;
 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilderBase;
 import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
@@ -142,6 +143,7 @@ abstract class AbstractAugmentGenerator
     final GeneratedType createTypeImpl(final TypeBuilderFactory builderFactory) {
         final GeneratedTypeBuilder builder = builderFactory.newGeneratedTypeBuilder(typeName());
 
+        YangSourceDefinition.of(currentModule().statement(), statement()).ifPresent(builder::setYangSourceDefinition);
         builder.addImplementsType(BindingTypes.augmentation(targetGenerator().getGeneratedType(builderFactory)));
         addUsesInterfaces(builder, builderFactory);
         addConcreteInterfaceMethods(builder);

diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/JavaFileTemplate.java b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/JavaFileTemplate.java
index 60ffe7f2ec08f4093478ca5cf83ed41aece282be..08dbd8b35955cb3b0d2c907e1fd1157014b795bd 100644 (file)
--- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/JavaFileTemplate.java
+++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/JavaFileTemplate.java
@@ -34,6 +34,7 @@ import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 import javax.annotation.processing.Generated;
 import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 import org.eclipse.xtext.xbase.lib.StringExtensions;
 import org.opendaylight.mdsal.binding.model.api.AnnotationType;
 import org.opendaylight.mdsal.binding.model.api.ConcreteType;
@@ -47,6 +48,7 @@ import org.opendaylight.mdsal.binding.model.api.Restrictions;
 import org.opendaylight.mdsal.binding.model.api.Type;
 import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition.Multiple;
 import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition.Single;
+import org.opendaylight.mdsal.binding.model.ri.BindingTypes;
 import org.opendaylight.mdsal.binding.model.ri.Types;
 import org.opendaylight.mdsal.binding.spec.naming.BindingMapping;
 import org.opendaylight.yangtools.yang.binding.Augmentable;
@@ -60,6 +62,7 @@ import org.opendaylight.yangtools.yang.model.api.SchemaNode;
 import org.opendaylight.yangtools.yang.model.api.YangStmtMapping;
 import org.opendaylight.yangtools.yang.model.api.meta.DeclaredStatement;
 import org.opendaylight.yangtools.yang.model.api.meta.EffectiveStatement;
+import org.opendaylight.yangtools.yang.model.api.stmt.AugmentEffectiveStatement;
 import org.opendaylight.yangtools.yang.model.api.stmt.ModuleEffectiveStatement;
 import org.opendaylight.yangtools.yang.model.export.DeclaredStatementFormatter;
 
@@ -402,8 +405,8 @@ class JavaFileTemplate {
         return false;
     }
 
-    static void appendSnippet(final StringBuilder sb, final GeneratedType type) {
-        type.getYangSourceDefinition().ifPresent(def -> {
+    final void appendSnippet(final StringBuilder sb, final GeneratedType genType) {
+        genType.getYangSourceDefinition().ifPresent(def -> {
             sb.append('\n');
 
             if (def instanceof Single single) {
@@ -422,7 +425,7 @@ class JavaFileTemplate {
 //                    sb.append("</i>\n");
 
                     if (hasBuilderClass(schema)) {
-                        final String builderName = type.getName() + BindingMapping.BUILDER_SUFFIX;
+                        final String builderName = genType.getName() + BindingMapping.BUILDER_SUFFIX;
 
                         sb.append("\n<p>To create instances of this class use {@link ").append(builderName)
                         .append("}.\n")
@@ -430,11 +433,18 @@ class JavaFileTemplate {
                         if (node instanceof ListSchemaNode) {
                             final var keyDef = ((ListSchemaNode) node).getKeyDefinition();
                             if (!keyDef.isEmpty()) {
-                                sb.append("@see ").append(type.getName()).append(BindingMapping.KEY_SUFFIX);
+                                sb.append("@see ").append(genType.getName()).append(BindingMapping.KEY_SUFFIX);
                             }
                             sb.append('\n');
                         }
                     }
+                } else if (node instanceof AugmentEffectiveStatement) {
+                    // Find target Augmentation<Foo> and reference Foo
+                    final var augType = findAugmentationArgument(genType);
+                    if (augType != null) {
+                        sb.append("\n\n")
+                        .append("@see ").append(importedName(augType));
+                    }
                 }
             } else if (def instanceof Multiple multiple) {
                 sb.append("<pre>\n");
@@ -446,6 +456,18 @@ class JavaFileTemplate {
         });
     }
 
+    private static @Nullable Type findAugmentationArgument(final GeneratedType genType) {
+        for (var implType : genType.getImplements()) {
+            if (implType instanceof ParameterizedType parameterized) {
+                final var augmentType = BindingTypes.extractAugmentable(parameterized);
+                if (augmentType != null) {
+                    return augmentType;
+                }
+            }
+        }
+        return null;
+    }
+
     static String encodeJavadocSymbols(final String description) {
         // FIXME: Use String.isBlank()?
         return description == null || description.isEmpty() ? description

diff --git a/binding/mdsal-binding-model-api/src/main/java/org/opendaylight/mdsal/binding/model/api/YangSourceDefinition.java b/binding/mdsal-binding-model-api/src/main/java/org/opendaylight/mdsal/binding/model/api/YangSourceDefinition.java
index 6177860706783fcdfbee9a7e16dfa4fc253da8b5..1e5ef44e48c6a0af602a91e2e83ea9287577f240 100644 (file)
--- a/binding/mdsal-binding-model-api/src/main/java/org/opendaylight/mdsal/binding/model/api/YangSourceDefinition.java
+++ b/binding/mdsal-binding-model-api/src/main/java/org/opendaylight/mdsal/binding/model/api/YangSourceDefinition.java
@@ -90,8 +90,8 @@ public abstract sealed class YangSourceDefinition {
 
     public static Optional<YangSourceDefinition> of(final ModuleEffectiveStatement module,
             final EffectiveStatement<?, ?> effective) {
-        return effective instanceof SchemaNode schema && effective.getDeclared() != null
-            ? Optional.of(new Single(module, schema)) : Optional.empty();
+        return effective instanceof DocumentedNode node && effective.getDeclared() != null
+                ? Optional.of(new Single(module, node)) : Optional.empty();
     }
 
     public static Optional<YangSourceDefinition> of(final Module module, final Collection<? extends SchemaNode> nodes) {

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 64d9c8dc9b887153403c3357142c6a1eae184bb0..511a96adb9635da16858d26edf2410e15e3f77d7 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
@@ -11,8 +11,10 @@ import static org.opendaylight.mdsal.binding.model.ri.Types.parameterizedTypeFor
 import static org.opendaylight.mdsal.binding.model.ri.Types.typeForClass;
 import static org.opendaylight.mdsal.binding.spec.naming.BindingMapping.VALUE_STATIC_FIELD_NAME;
 
+import com.google.common.annotations.Beta;
 import com.google.common.annotations.VisibleForTesting;
 import org.eclipse.jdt.annotation.NonNull;
+import org.eclipse.jdt.annotation.Nullable;
 import org.opendaylight.mdsal.binding.model.api.ConcreteType;
 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject;
 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
@@ -315,4 +317,25 @@ public final class BindingTypes {
         }
         return false;
     }
+
+    /**
+     * Return the {@link Augmentable} type a parameterized {@link Augmentation} type references.
+     *
+     * @param type Parameterized type
+     * @return Augmentable target, or null if {@code type} does not match the result of {@link #augmentation(Type)}
+     * @throws NullPointerException if {@code type} is null
+     */
+    @Beta
+    public static @Nullable Type extractAugmentable(final ParameterizedType type) {
+        if (AUGMENTATION.equals(type.getRawType())) {
+            final var args = type.getActualTypeArguments();
+            if (args.length == 1) {
+                final var arg = args[0];
+                if (arg != null) {
+                    return arg;
+                }
+            }
+        }
+        return null;
+    }
 }