From 46d3e5401d9c182c12819351b79176ad4354a5c1 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Wed, 27 Apr 2022 16:49:58 +0200
Subject: [PATCH] Document builder constructors

Javadoc is not entirely happy with us not generating any documentation
for various Builder constructors. Fix this by adding some rudimentary
javadoc.

JIRA: MDSAL-755
Change-Id: Icaec59bb86d21f372e341ea93d9d89cbb2599951
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
(cherry picked from commit 11fa023df13dfc3b4cd368e71146319cc0368c82)
---
 .../java/api/generator/BuilderTemplate.xtend  | 31 ++++++++++++++-----
 1 file changed, 24 insertions(+), 7 deletions(-)

diff --git a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
index 70f4563316..2a23fe1a90 100644
--- a/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
+++ b/binding/mdsal-binding-java-api-generator/src/main/java/org/opendaylight/mdsal/binding/java/api/generator/BuilderTemplate.xtend
@@ -73,8 +73,21 @@ class BuilderTemplate extends AbstractBuilderTemplate {
                 «generateAugmentField()»
             «ENDIF»
 
+            /**
+             * Construct an empty builder.
+             */
+            public «type.name»() {
+                // No-op
+            }
+
             «generateConstructorsFromIfcs()»
 
+            «val targetTypeName = targetType.importedName»
+            /**
+             * Construct a builder initialized with state from specified {@link «targetTypeName»}.
+             *
+             * @param base «targetTypeName» from which the builder should be initialized
+             */
             public «generateCopyConstructor(targetType, type.enclosedTypes.get(0))»
 
             «generateMethodFieldsFrom()»
@@ -88,11 +101,11 @@ class BuilderTemplate extends AbstractBuilderTemplate {
             «generateSetters»
 
             /**
-             * A new {@link «targetType.name»} instance.
+             * A new {@link «targetTypeName»} instance.
              *
-             * @return A new {@link «targetType.name»} instance.
+             * @return A new {@link «targetTypeName»} instance.
              */
-            public «targetType.name» build() {
+            public «targetTypeName» build() {
                 return new «type.enclosedTypes.get(0).importedName»(this);
             }
 
@@ -112,9 +125,6 @@ class BuilderTemplate extends AbstractBuilderTemplate {
      * Generate default constructor and constructor for every implemented interface from uses statements.
      */
     def private generateConstructorsFromIfcs() '''
-        public «type.name»() {
-        }
-
         «IF (!(targetType instanceof GeneratedTransferObject))»
             «FOR impl : targetType.implements SEPARATOR "\n"»
                 «generateConstructorFromIfc(impl)»
@@ -128,9 +138,16 @@ class BuilderTemplate extends AbstractBuilderTemplate {
     def private Object generateConstructorFromIfc(Type impl) '''
         «IF (impl instanceof GeneratedType)»
             «IF impl.hasNonDefaultMethods»
-                public «type.name»(«impl.importedName» arg) {
+                «val typeName = impl.importedName»
+                /**
+                 * Construct a new builder initialized from specified {@link «typeName»}.
+                 *
+                 * @param arg «typeName» from which the builder should be initialized
+                 */
+                public «type.name»(«typeName» arg) {
                     «printConstructorPropertySetter(impl)»
                 }
+
             «ENDIF»
             «FOR implTypeImplement : impl.implements»
                 «generateConstructorFromIfc(implTypeImplement)»
-- 
2.36.6