Improve StmtContext.buildEffective() documentation

This method's contract is a bit under-specified in terms of expected
implementation behaviour and as to how nulls are treated. Improve that
a bit.

JIRA: YANGTOOLS-1214
Change-Id: Ie2043d8af803376077b10bba6a53a1959c0a6ed3
Signed-off-by: Robert Varga <robert.varga@pantheon.tech>

diff --git a/yang/yang-parser-reactor/src/main/java/org/opendaylight/yangtools/yang/parser/stmt/reactor/ReactorStmtCtx.java b/yang/yang-parser-reactor/src/main/java/org/opendaylight/yangtools/yang/parser/stmt/reactor/ReactorStmtCtx.java
index a1ac8ffd1f7c75686ac4302ad9851a5e2093c5f0..54f1a3c42ab955140f8cad9161ea168a8677cca2 100644 (file)
--- a/yang/yang-parser-reactor/src/main/java/org/opendaylight/yangtools/yang/parser/stmt/reactor/ReactorStmtCtx.java
+++ b/yang/yang-parser-reactor/src/main/java/org/opendaylight/yangtools/yang/parser/stmt/reactor/ReactorStmtCtx.java
@@ -356,7 +356,7 @@ abstract class ReactorStmtCtx<A, D extends DeclaredStatement<A>, E extends Effec
         return (existing = effectiveInstance) != null ? existing : loadEffective();
     }
 
-    private E loadEffective() {
+    private @NonNull E loadEffective() {
         // Creating an effective statement does not strictly require a declared instance -- there are statements like
         // 'input', which are implicitly defined.
         // Our implementation design makes an invariant assumption that buildDeclared() has been called by the time

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 61f0ff85cd6eced3c4d9ba287976bb103e0be212..af2d10d03f29df8435e42f8333bc305e30a14083 100644 (file)
--- 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
@@ -147,9 +147,15 @@ public interface StmtContext<A, D extends DeclaredStatement<A>, E extends Effect
     }
 
     /**
-     * Builds {@link EffectiveStatement} for statement context.
+     * Return the {@link EffectiveStatement} for statement context, creating it if required. Implementations of this
+     * method are required to memoize the returned object, so that subsequent invocation return the same object.
+     *
+     * <p>
+     * If {@link #isSupportedToBuildEffective()} returns {@code false}, this method's behaviour is undefined.
+     *
+     * @return Effective statement instance.
      */
-    E buildEffective();
+    @NonNull E buildEffective();
 
     boolean isSupportedToBuildEffective();