From ee61e8811b57bd2dc3218ec1c771e844f5cc3ead Mon Sep 17 00:00:00 2001
From: Robert Varga <robert.varga@pantheon.tech>
Date: Mon, 9 Jul 2018 18:45:25 +0200
Subject: [PATCH] Update ModuleActionBuilder and StmtContext documentation

This patch clarifies the API contract around reactor primitives,
so it is clearer as to what the arguments and methods mean.

JIRA: YANGTOOLS-859
Change-Id: I8c4eed7c43dc217547cce57855768b342a698b90
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>
---
 .../parser/spi/meta/ModelActionBuilder.java   | 24 +++++++++++++++----
 .../yang/parser/spi/meta/StmtContext.java     |  3 ++-
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/ModelActionBuilder.java b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/ModelActionBuilder.java
index 9f59d5ec1b..08d01cb9f1 100644
--- a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/ModelActionBuilder.java
+++ b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/ModelActionBuilder.java
@@ -143,7 +143,8 @@ public interface ModelActionBuilder {
         Prerequisite<D> requiresDeclared(StmtContext<?, ?, ?> context, Class<N> namespace, K key);
 
     /**
-     * Action requires that the specified context completes specified phase.
+     * Action requires that the specified context completes specified phase before {@link #apply(InferenceAction)}
+     * may be invoked.
      *
      * @param context Statement context which needs to complete the transition.
      * @param phase ModelProcessingPhase which must have completed
@@ -159,14 +160,29 @@ public interface ModelActionBuilder {
             StmtContext<?, ?, ?> context, Class<N> namespace, NamespaceKeyCriterion<K> criterion,
             ModelProcessingPhase phase);
 
-    default @Nonnull <T extends Mutable<?, ?, ?>> Prerequisite<T> mutatesEffectiveCtx(final T stmt) {
-        return mutatesCtx(stmt, EFFECTIVE_MODEL);
+    /**
+     * Action mutates the effective model of specified statement. This is a shorthand for
+     * {@code mutatesCtx(context, EFFECTIVE_MODEL}.
+     *
+     * @param context Target statement context
+     * @return A {@link Prerequisite} returning the requested context.
+     */
+    default @Nonnull <T extends Mutable<?, ?, ?>> Prerequisite<T> mutatesEffectiveCtx(final T context) {
+        return mutatesCtx(context, EFFECTIVE_MODEL);
     }
 
     @Nonnull <K, E extends EffectiveStatement<?, ?>, N extends IdentifierNamespace<K, ? extends StmtContext<?, ?, ?>>>
         Prerequisite<Mutable<?, ?, E>> mutatesEffectiveCtx(StmtContext<?, ?, ?> context, Class<N> namespace, K key);
 
-    @Nonnull <C extends Mutable<?, ?, ?>, T extends C> Prerequisite<C> mutatesCtx(T root, ModelProcessingPhase phase);
+    /**
+     * Action mutates the specified statement in the specified phase. Target statement cannot complete specified
+     * phase before this action is applier.
+     *
+     * @param context Target statement context
+     * @return A {@link Prerequisite} returning the requested context.
+     */
+    @Nonnull <C extends Mutable<?, ?, ?>, T extends C> Prerequisite<C> mutatesCtx(T context,
+            ModelProcessingPhase phase);
 
     /**
      * Apply an {@link InferenceAction} when this action's prerequisites are resolved.
diff --git a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/StmtContext.java b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/StmtContext.java
index 29a7cdf9f3..3d9e4e7dcf 100644
--- a/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/StmtContext.java
+++ b/yang/yang-parser-spi/src/main/java/org/opendaylight/yangtools/yang/parser/spi/meta/StmtContext.java
@@ -212,7 +212,8 @@ public interface StmtContext<A, D extends DeclaredStatement<A>, E extends Effect
 
         /**
          * Create a new inference action to be executed during specified phase. The action cannot be cancelled
-         * and will be executed even if its definition remains incomplete.
+         * and will be executed even if its definition remains incomplete. The specified phase cannot complete until
+         * this action is resolved. If the action cannot be resolved, model processing will fail.
          *
          * @param phase Target phase in which the action will resolved.
          * @return A new action builder.
-- 
2.36.6