From: Samuel Schneider Date: Wed, 17 Aug 2022 08:07:50 +0000 (+0200) Subject: Generate javadoc for TypeObjects X-Git-Tag: v10.0.2~1 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=4c816af63600b419b40293287785501218e50135;p=mdsal.git 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 Signed-off-by: Robert Varga --- 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 45e7f80b5b..ad67c26c75 100644 --- 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, 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 tmp = new ArrayList<>(1); @@ -600,18 +601,19 @@ abstract class AbstractTypeObjectGenerator, 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, 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, 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, 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 bcebb15b34..d523b60f8d 100644 --- 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 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 1aa3d126cf..d161cbedf1 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 @@ -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("
\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 53c3fdea56..04372a8b11 100644
--- 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 abe3427bec..595b87eaa8 100644
--- 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 getSchemaPath() {
-            return this.schemaPath.getPathFromRoot();
+            return schemaPath.getPathFromRoot();
         }
 
         @Override
         public String getModuleName() {
-            return this.moduleName;
+            return moduleName;
         }
 
         @Override
         public Optional 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 cfbd42ddab..c3903f9e89 100644
--- 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);