Add some Generator documentation

Add a bit of explanation on how the generator tree is organized and drop
a few FIXMEs for things we want to get rid of in the long term.

Change-Id: I7c7820aeadcce0e2a69ff3033d5c2efc75b2dda3
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/AbstractImplicitGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractImplicitGenerator.java
index f1fb55071f3f5d118d41b5a651454942cc0cb01e..9b93edfbff35985f2be361c03225844be139d52e 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractImplicitGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/AbstractImplicitGenerator.java
@@ -12,8 +12,10 @@ import org.opendaylight.mdsal.binding.generator.impl.reactor.CollisionDomain.Mem
 import org.opendaylight.yangtools.yang.model.util.SchemaInferenceStack;
 
 /**
- * An implicit {@link Generator}, not associated with any particular statement.
+ * An implicit {@link Generator}, not associated with any particular statement. We use these only for aggregate services
+ * harking back to the original specification for Java 7. As such we want to eventually get rid of it.
  */
+// FIXME: eventually remove this subclass and unify Generator and AbstractExplicitGenerator
 abstract class AbstractImplicitGenerator extends Generator {
     AbstractImplicitGenerator(final ModuleGenerator parent) {
         super(parent);

diff --git a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/Generator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/Generator.java
index 7f639216a2bdec24210932ffa86c2c8ab4c065e8..99580eddbb6be3a64ca67088059ff21b259c7291 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/Generator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/Generator.java
@@ -52,6 +52,14 @@ import org.opendaylight.yangtools.yang.model.util.SchemaInferenceStack;
 /**
  * A single node in generator tree. Each node will eventually resolve to a generated Java class. Each node also can have
  * a number of children, which are generators corresponding to the YANG subtree of this node.
+ *
+ * <p>
+ * Each tree is rooted in a {@link ModuleGenerator} and its organization follows roughly YANG {@code schema tree}
+ * layout, but with a twist coming from the reuse of generated interfaces from a {@code grouping} in the location of
+ * every {@code uses} encountered and also the corresponding backwards propagation of {@code augment} effects.
+ *
+ * <p>
+ * Overall the tree layout guides the allocation of Java package and top-level class namespaces.
  */
 public abstract class Generator implements Iterable<Generator> {
     private static final JavaTypeName DEPRECATED_ANNOTATION = JavaTypeName.create(Deprecated.class);

diff --git a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/NotificationServiceGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/NotificationServiceGenerator.java
index 4b6f415f721ed11248908db2e89be7a42776ffe7..cfde7ed9a0193755d5e0a66a45d88095da2fa0bb 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/NotificationServiceGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/NotificationServiceGenerator.java
@@ -22,6 +22,11 @@ import org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus;
 import org.opendaylight.yangtools.yang.model.api.Status;
 import org.opendaylight.yangtools.yang.model.api.stmt.NotificationEffectiveStatement;
 
+/**
+ * Aggregate service for top-level {@code notification} statements for a particular module. It does not handle nested
+ * (YANG 1.1) notifications.
+ */
+// FIXME: eventually remove this generator
 final class NotificationServiceGenerator extends AbstractImplicitGenerator {
     private final List<NotificationGenerator> notifs;
 
@@ -38,6 +43,7 @@ final class NotificationServiceGenerator extends AbstractImplicitGenerator {
     @Override
     GeneratedType createTypeImpl(final TypeBuilderFactory builderFactory) {
         final GeneratedTypeBuilder builder = builderFactory.newGeneratedTypeBuilder(typeName());
+        // FIXME: MDSAL-496: mark this interface as deprecated
         builder.addImplementsType(BindingTypes.NOTIFICATION_LISTENER);
 
         for (NotificationGenerator gen : notifs) {

diff --git a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/RpcServiceGenerator.java b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/RpcServiceGenerator.java
index a11ed784ab1919b1e7119c5598d778effb3607ae..87497dbec0fbb779bc3e9ff97a52ed6f3c09e012 100644 (file)
--- a/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/RpcServiceGenerator.java
+++ b/binding/mdsal-binding-generator/src/main/java/org/opendaylight/mdsal/binding/generator/impl/reactor/RpcServiceGenerator.java
@@ -24,6 +24,10 @@ import org.opendaylight.yangtools.yang.model.api.stmt.InputEffectiveStatement;
 import org.opendaylight.yangtools.yang.model.api.stmt.OutputEffectiveStatement;
 import org.opendaylight.yangtools.yang.model.api.stmt.RpcEffectiveStatement;
 
+/**
+ * Aggregate service for top-level {@code rpc} statements for a particular module.
+ */
+// FIXME: eventually remove this generator
 final class RpcServiceGenerator extends AbstractImplicitGenerator {
     private static final JavaTypeName CHECK_RETURN_VALUE_ANNOTATION =
         // Do not refer to annotation class, as it may not be available at runtime