Generate javadoc for TypeObjects

Fix warnings about missing javadoc in TypeObject classes.

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

Generation of javadoc was added for all TypeObjects not only
ScalarTypes as described in corresponding task.

JIRA: MDSAL-762
Change-Id: Iec3ab9e36bcea0807892bd024b7f04c451ff9000
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/AbstractTypeObjectGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractTypeObjectGenerator.java
index 45e7f80b5bb62535959e1259ffbc0b22d65d759f..ad67c26c75ac5ae750b9e4c2ba923e2763c681a0 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractTypeObjectGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractTypeObjectGenerator.java
@@ -589,9 +589,10 @@ abstract class AbstractTypeObjectGenerator<S extends EffectiveStatement<?, ?>, R
         final boolean isTypedef = this instanceof TypedefGenerator;
         final QName arg = type.argument();
         if (TypeDefinitions.BITS.equals(arg)) {
-            return createBits(builderFactory, typeName(), currentModule(), extractTypeDefinition(), isTypedef);
+            return createBits(builderFactory, statement(), typeName(), currentModule(), extractTypeDefinition(),
+                    isTypedef);
         } else if (TypeDefinitions.ENUMERATION.equals(arg)) {
-            return createEnumeration(builderFactory, typeName(), currentModule(),
+            return createEnumeration(builderFactory, statement(), typeName(), currentModule(),
                 (EnumTypeDefinition) extractTypeDefinition());
         } else if (TypeDefinitions.UNION.equals(arg)) {
             final List<GeneratedType> tmp = new ArrayList<>(1);
@@ -600,18 +601,19 @@ abstract class AbstractTypeObjectGenerator<S extends EffectiveStatement<?, ?>, R
             auxiliaryGeneratedTypes = List.copyOf(tmp);
             return ret;
         } else {
-            return createSimple(builderFactory, typeName(), currentModule(),
+            return createSimple(builderFactory, statement(), typeName(), currentModule(),
                 verifyNotNull(SIMPLE_TYPES.get(arg), "Unhandled type %s", arg), extractTypeDefinition());
         }
     }
 
     private static @NonNull GeneratedTransferObject createBits(final TypeBuilderFactory builderFactory,
-            final JavaTypeName typeName, final ModuleGenerator module, final TypeDefinition<?> typedef,
-            final boolean isTypedef) {
+            final EffectiveStatement<?, ?> definingStatement, final JavaTypeName typeName, final ModuleGenerator module,
+            final TypeDefinition<?> typedef, final boolean isTypedef) {
         final GeneratedTOBuilder builder = builderFactory.newGeneratedTOBuilder(typeName);
         builder.setTypedef(isTypedef);
         builder.addImplementsType(BindingTypes.TYPE_OBJECT);
         builder.setBaseType(typedef);
+        YangSourceDefinition.of(module.statement(), definingStatement).ifPresent(builder::setYangSourceDefinition);
 
         for (Bit bit : ((BitsTypeDefinition) typedef).getBits()) {
             final String name = bit.getName();
@@ -633,9 +635,11 @@ abstract class AbstractTypeObjectGenerator<S extends EffectiveStatement<?, ?>, R
     }
 
     private static @NonNull Enumeration createEnumeration(final TypeBuilderFactory builderFactory,
-            final JavaTypeName typeName, final ModuleGenerator module, final EnumTypeDefinition typedef) {
+            final EffectiveStatement<?, ?> definingStatement, final JavaTypeName typeName,
+            final ModuleGenerator module, final EnumTypeDefinition typedef) {
         // TODO units for typedef enum
         final AbstractEnumerationBuilder builder = builderFactory.newEnumerationBuilder(typeName);
+        YangSourceDefinition.of(module.statement(), definingStatement).ifPresent(builder::setYangSourceDefinition);
 
         typedef.getDescription().map(BindingGeneratorUtil::encodeAngleBrackets)
             .ifPresent(builder::setDescription);
@@ -647,12 +651,13 @@ abstract class AbstractTypeObjectGenerator<S extends EffectiveStatement<?, ?>, R
     }
 
     private static @NonNull GeneratedType createSimple(final TypeBuilderFactory builderFactory,
-            final JavaTypeName typeName, final ModuleGenerator module, final Type javaType,
-            final TypeDefinition<?> typedef) {
+            final EffectiveStatement<?, ?> definingStatement, final JavaTypeName typeName, final ModuleGenerator module,
+            final Type javaType, final TypeDefinition<?> typedef) {
         final String moduleName = module.statement().argument().getLocalName();
         final GeneratedTOBuilder builder = builderFactory.newGeneratedTOBuilder(typeName);
         builder.setTypedef(true);
         builder.addImplementsType(BindingTypes.scalarTypeObject(javaType));
+        YangSourceDefinition.of(module.statement(), definingStatement).ifPresent(builder::setYangSourceDefinition);
 
         final GeneratedPropertyBuilder genPropBuilder = builder.addProperty(TypeConstants.VALUE_PROP);
         genPropBuilder.setReturnType(javaType);
@@ -720,13 +725,13 @@ abstract class AbstractTypeObjectGenerator<S extends EffectiveStatement<?, ?>, R
                     propSource = subUnionName.simpleName();
                     generatedType = subUnion;
                 } else if (TypeDefinitions.ENUMERATION.equals(subName)) {
-                    final Enumeration subEnumeration = createEnumeration(builderFactory,
+                    final Enumeration subEnumeration = createEnumeration(builderFactory, definingStatement,
                         typeName.createEnclosed(BindingMapping.getClassName(localName), "$"), module,
                         (EnumTypeDefinition) subType.getTypeDefinition());
                     builder.addEnumeration(subEnumeration);
                     generatedType = subEnumeration;
                 } else if (TypeDefinitions.BITS.equals(subName)) {
-                    final GeneratedTransferObject subBits = createBits(builderFactory,
+                    final GeneratedTransferObject subBits = createBits(builderFactory, definingStatement,
                         typeName.createEnclosed(BindingMapping.getClassName(localName), "$"), module,
                         subType.getTypeDefinition(), isTypedef);
                     builder.addEnclosingTransferObject(subBits);

diff --git a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/TypedefGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/TypedefGenerator.java
index bcebb15b340c720666d3eacdc6d126e98d45d7ef..d523b60f8dfeacb21565001a99a92a46e8330a61 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/TypedefGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/TypedefGenerator.java
@@ -16,6 +16,7 @@ import org.opendaylight.mdsal.binding.generator.impl.rt.DefaultTypedefRuntimeTyp
 import org.opendaylight.mdsal.binding.model.api.GeneratedTransferObject;
 import org.opendaylight.mdsal.binding.model.api.GeneratedType;
 import org.opendaylight.mdsal.binding.model.api.Type;
+import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition;
 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTOBuilder;
 import org.opendaylight.mdsal.binding.model.api.type.builder.GeneratedTypeBuilderBase;
 import org.opendaylight.mdsal.binding.runtime.api.TypedefRuntimeType;
@@ -84,6 +85,7 @@ final class TypedefGenerator extends AbstractTypeObjectGenerator<TypedefEffectiv
         builder.setExtendsType(baseType);
         builder.setIsUnion(baseType.isUnionType());
         builder.setRestrictions(computeRestrictions());
+        YangSourceDefinition.of(currentModule().statement(), statement()).ifPresent(builder::setYangSourceDefinition);
 
         final TypeDefinition<?> typedef = statement().getTypeDefinition();
         annotateDeprecatedIfNecessary(typedef, 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 1aa3d126cf8fd0e7ef0b5f3a43b432fa71ae8820..d161cbedf11822e04908976f1a8991cca682d03c 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
@@ -64,6 +64,7 @@ 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.api.stmt.TypedefEffectiveStatement;
 import org.opendaylight.yangtools.yang.model.export.DeclaredStatementFormatter;
 
 /**
@@ -453,6 +454,13 @@ class JavaFileTemplate {
                         .append("@see ").append(importedName(augType));
                     }
                 }
+                if (node instanceof TypedefEffectiveStatement && genType instanceof GeneratedTransferObject genTO) {
+                    final var augType = genTO.getSuperType();
+                    if (augType != null) {
+                        sb.append("\n\n")
+                        .append("@see ").append(augType.getName());
+                    }
+                }
             } else if (def instanceof Multiple multiple) {
                 sb.append("<pre>\n");
                 for (SchemaNode node : multiple.getNodes()) {

diff --git a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/AbstractEnumerationBuilder.java b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/AbstractEnumerationBuilder.java
index 53c3fdea56117aa6bd28c7fc8eaacc9422c1b464..04372a8b113daa35f4a944623f06ad63edb0c615 100644 (file)
--- a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/AbstractEnumerationBuilder.java
+++ b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/AbstractEnumerationBuilder.java
@@ -24,6 +24,7 @@ import org.opendaylight.mdsal.binding.model.api.GeneratedType;
 import org.opendaylight.mdsal.binding.model.api.JavaTypeName;
 import org.opendaylight.mdsal.binding.model.api.MethodSignature;
 import org.opendaylight.mdsal.binding.model.api.Type;
+import org.opendaylight.mdsal.binding.model.api.YangSourceDefinition;
 import org.opendaylight.mdsal.binding.model.api.type.builder.AnnotationTypeBuilder;
 import org.opendaylight.mdsal.binding.model.api.type.builder.EnumBuilder;
 import org.opendaylight.mdsal.binding.spec.naming.BindingMapping;
@@ -65,6 +66,8 @@ public abstract class AbstractEnumerationBuilder extends AbstractType implements
 
     public abstract void setSchemaPath(SchemaPath schemaPath);
 
+    public abstract void setYangSourceDefinition(YangSourceDefinition yangSourceDefinition);
+
     abstract AbstractPair createEnumPair(String name, String mappedName, int value, Status status, String description,
             String reference);
 

diff --git a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/CodegenEnumerationBuilder.java b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/CodegenEnumerationBuilder.java
index abe3427becd94a0797802a54fa9b0880672f2126..595b87eaa885aa53f0c98157be4f4c139519b363 100644 (file)
--- a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/CodegenEnumerationBuilder.java
+++ b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/CodegenEnumerationBuilder.java
@@ -23,6 +23,7 @@ public final class CodegenEnumerationBuilder extends AbstractEnumerationBuilder
     private String reference;
     private String moduleName;
     private SchemaPath schemaPath;
+    private YangSourceDefinition definition;
 
     public CodegenEnumerationBuilder(final JavaTypeName identifier) {
         super(identifier);
@@ -46,7 +47,11 @@ public final class CodegenEnumerationBuilder extends AbstractEnumerationBuilder
     @Override
     public void setDescription(final String description) {
         this.description = description;
+    }
 
+    @Override
+    public void setYangSourceDefinition(final YangSourceDefinition yangSourceDefinition) {
+        this.definition = yangSourceDefinition;
     }
 
     @Override
@@ -94,13 +99,15 @@ public final class CodegenEnumerationBuilder extends AbstractEnumerationBuilder
         private final String reference;
         private final String moduleName;
         private final SchemaPath schemaPath;
+        private final YangSourceDefinition definition;
 
         EnumerationImpl(final CodegenEnumerationBuilder builder) {
             super(builder);
-            this.description = builder.description;
-            this.moduleName = builder.moduleName;
-            this.schemaPath = builder.schemaPath;
-            this.reference = builder.reference;
+            description = builder.description;
+            moduleName = builder.moduleName;
+            schemaPath = builder.schemaPath;
+            reference = builder.reference;
+            definition = builder.definition;
         }
 
         @Override
@@ -110,27 +117,27 @@ public final class CodegenEnumerationBuilder extends AbstractEnumerationBuilder
 
         @Override
         public String getDescription() {
-            return this.description;
+            return description;
         }
 
         @Override
         public String getReference() {
-            return this.reference;
+            return reference;
         }
 
         @Override
         public Iterable<QName> getSchemaPath() {
-            return this.schemaPath.getPathFromRoot();
+            return schemaPath.getPathFromRoot();
         }
 
         @Override
         public String getModuleName() {
-            return this.moduleName;
+            return moduleName;
         }
 
         @Override
         public Optional<YangSourceDefinition> getYangSourceDefinition() {
-            return Optional.empty();
+            return Optional.ofNullable(definition);
         }
     }
 }

diff --git a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/RuntimeEnumerationBuilder.java b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/RuntimeEnumerationBuilder.java
index cfbd42ddabdf3cf540c3cb6a0e0784925d75c4d1..c3903f9e89f824880d59b36c78b2649b8837ecef 100644 (file)
--- a/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/RuntimeEnumerationBuilder.java
+++ b/binding/mdsal-binding-model-ri/src/main/java/org/opendaylight/mdsal/binding/model/ri/generated/type/builder/RuntimeEnumerationBuilder.java
@@ -41,6 +41,11 @@ public final class RuntimeEnumerationBuilder extends AbstractEnumerationBuilder
         // No-op
     }
 
+    @Override
+    public void setYangSourceDefinition(final YangSourceDefinition definition) {
+        // No-op
+    }
+
     @Override
     public Enumeration toInstance() {
         return new EnumerationImpl(this);