Expand reactor documentation a bit

[yangtools.git] / yang / yang-parser-spi / src / main / java / org / opendaylight / yangtools / yang / parser / spi / meta / StmtContext.java

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 4566ba91903fd0bb70029eb47a96a42aade719b9..39c7bcfd0291f7b2b3391cb8baa694e9e59f150e 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
@@ -29,12 +29,31 @@ import org.opendaylight.yangtools.yang.model.api.meta.StatementSource;
 import org.opendaylight.yangtools.yang.model.repo.api.SourceIdentifier;
 import org.opendaylight.yangtools.yang.parser.spi.source.StatementSourceReference;
 
+/**
+ * An inference context associated with an instance of a statement.
+ *
+ * @param <A> Argument type
+ * @param <D> Declared Statement representation
+ * @param <E> Effective Statement representation
+ */
 public interface StmtContext<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>> {
-
+    /**
+     * Returns the origin of the statement.
+     *
+     * @return origin of statement
+     */
     @NonNull StatementSource getStatementSource();
 
+    /**
+     * Returns a reference to statement source.
+     *
+     * @return reference of statement source
+     */
     @NonNull StatementSourceReference getStatementSourceReference();
 
+    /**
+     * See {@link StatementSupport#getPublicView()}.
+     */
     @NonNull StatementDefinition getPublicDefinition();
 
     /**
@@ -155,14 +174,45 @@ public interface StmtContext<A, D extends DeclaredStatement<A>, E extends Effect
 
     boolean isSupportedToBuildEffective();
 
+    boolean isSupportedByFeatures();
+
     Collection<? extends StmtContext<?, ?, ?>> getEffectOfStatement();
 
-    CopyHistory getCopyHistory();
+    /*
+     * FIXME: YANGTOOLS-784: the next three methods are closely related to the copy process:
+     *        - getCopyHistory() is a brief summary of what went on
+     *        - getOriginalContext() points to the CopyHistory.ORIGINAL
+     *        - getPreviousCopyCtx() points to the immediate predecessor forming a singly-linked list terminated
+     *          at getOriginalContext()
+     *
+     *        When implementing YANGTOOLS-784, this needs to be taken into account and properly forwarded through
+     *        intermediate MutableTrees. Also note this closely relates to current namespace context, as taken into
+     *        account when creating the argument. At least parts of this are only needed during buildEffective()
+     *        and hence should become arguments to that method.
+     */
 
-    boolean isSupportedByFeatures();
+    /**
+     * Return the executive summary of the copy process that has produced this context.
+     *
+     * @return A simplified summary of the copy process.
+     */
+    CopyHistory getCopyHistory();
 
+    /**
+     * Return the statement context of the original definition, if this statement is an instantiated copy.
+     *
+     * @return Original definition, if this statement was copied.
+     */
     Optional<StmtContext<?, ?, ?>> getOriginalCtx();
 
+    /**
+     * Return the context of the previous copy of this statement -- effectively walking towards the source origin
+     * of this statement.
+     *
+     * @return Context of the previous copy of this statement, if this statement has been copied.
+     */
+    Optional<? extends StmtContext<?, ?, ?>> getPreviousCopyCtx();
+
     ModelProcessingPhase getCompletedPhase();
 
     /**
@@ -172,6 +222,13 @@ public interface StmtContext<A, D extends DeclaredStatement<A>, E extends Effect
      */
     @NonNull YangVersion getRootVersion();
 
+    /**
+     * An mutable view of an inference context associated with an instance of a statement.
+     *
+     * @param <A> Argument type
+     * @param <D> Declared Statement representation
+     * @param <E> Effective Statement representation
+     */
     interface Mutable<A, D extends DeclaredStatement<A>, E extends EffectiveStatement<A, D>>
             extends StmtContext<A, D, E> {
 
@@ -215,6 +272,8 @@ public interface StmtContext<A, D extends DeclaredStatement<A>, E extends Effect
          *                                  from an alien implementation.
          * @throws org.opendaylight.yangtools.yang.parser.spi.source.SourceException instance of SourceException
          */
+        // FIXME: 5.0.0: remove generic arguments X, Y, Z. Callers should not care, as the returned copy can actually
+        //               be an encapsulating implicit statement.
         <X, Y extends DeclaredStatement<X>, Z extends EffectiveStatement<X, Y>> Mutable<X, Y, Z> childCopyOf(
                 StmtContext<X, Y, Z> stmt, CopyType type, @Nullable QNameModule targetModule);