From: Samuel Schneider Date: Thu, 4 Aug 2022 13:13:00 +0000 (+0200) Subject: Generate javadoc for augments X-Git-Tag: v10.0.1~19 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=0c5de237458d3d6a5f91c03012fa6ba779849ca2;p=mdsal.git 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 Signed-off-by: Robert Varga --- 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 d2ae1890ae..d48e841929 100644 --- 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 60ffe7f2ec..08dbd8b359 100644 --- 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("\n"); if (hasBuilderClass(schema)) { - final String builderName = type.getName() + BindingMapping.BUILDER_SUFFIX; + final String builderName = genType.getName() + BindingMapping.BUILDER_SUFFIX; sb.append("\n

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 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("

\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 6177860706..1e5ef44e48 100644
--- 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 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 of(final Module module, final Collection 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 64d9c8dc9b..511a96adb9 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
@@ -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;
+    }
 }