Improve generated builder documentation

[mdsal.git] / binding / mdsal-binding-java-api-generator / src / main / java / org / opendaylight / mdsal / binding / java / api / generator / BuilderTemplate.xtend

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 4be3ad4922e3be5cdc96ebd4f221aabe6160bce4..e3a9ccef88da763b736d13424645714113a545bb 100644 (file)
--- 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»
     '''
     }