From 1c11427fc685e19c6fa666e5d97462113060bd03 Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Tue, 3 Sep 2019 22:01:24 +0200
Subject: [PATCH] Improve generated builder documentation

This adds some sorely-needed guidelines as to how to use generated
builders.

Change-Id: I786a7e2f249f336363d4ddc107919edb861e0422
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../java/api/generator/BuilderTemplate.xtend  | 42 +++++++++++++++++--
 1 file changed, 38 insertions(+), 4 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 4be3ad4922..e3a9ccef88 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
@@ -369,11 +369,45 @@ class BuilderTemplate extends AbstractBuilderTemplate {
         «ENDIF»
     '''
 
-    private def createDescription(GeneratedType type) {
+    private def createDescription(GeneratedType targetType) {
+        val target = type.importedName
         return '''
-        Class that builds {@link «type.importedName»} instances.
-
-        @see «type.importedName»
+        Class that builds {@link «target»} instances. Overall design of the class is that of a
+        <a href="https://en.wikipedia.org/wiki/Fluent_interface">fluent interface</a>, where method chaining is used.
+
+        <p>
+        In general, this class is supposed to be used like this template:
+        <pre>
+          <code>
+            «target» createTarget(int fooXyzzy, int barBaz) {
+                return new «target»Builder()
+                    .setFoo(new FooBuilder().setXyzzy(fooXyzzy).build())
+                    .setBar(new BarBuilder().setBaz(barBaz).build())
+                    .build();
+            }
+          </code>
+        </pre>
+
+        <p>
+        This pattern is supported by the immutable nature of «target», as instances can be freely passed around without
+        worrying about synchronization issues.
+
+        <p>
+        As a side note: method chaining results in:
+        <ul>
+          <li>very efficient Java bytecode, as the method invocation result, in this case the Builder reference, is
+              on the stack, so further method invocations just need to fill method arguments for the next method
+              invocation, which is terminated by {@link #build()}, which is then returned from the method</li>
+          <li>better understanding by humans, as the scope of mutable state (the builder) is kept to a minimum and is
+              very localized</li>
+          <li>better optimization oportunities, as the object scope is minimized in terms of invocation (rather than
+              method) stack, making <a href="https://en.wikipedia.org/wiki/Escape_analysis">escape analysis</a> a lot
+              easier. Given enough compiler (JIT/AOT) prowess, the cost of th builder object can be completely
+              eliminated</li>
+        </ul>
+
+        @see «target»
+        @see «Builder.importedName»
     '''
     }
 
-- 
2.36.6