Upd docs for StateFrame & add docs for StateFrameStack

reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/StateFrame.kt

@@ -21,16 +21,15 @@ import jetbrains.mps.logic.reactor.logical.Logical
 import jetbrains.mps.logic.reactor.util.*
 
 /**
- * A StateFrame captures a processing state corresponding to an event that consists
- * of an activated constraint occurrence followed by a series of triggered rule
- * matches.
+ * A [StateFrame] captures a processing state corresponding to current relevant
+ * observers of changes of logical variables. It roughly corresponds to an event
+ * that updates a set of such observers. By dropping a frame the processing state
+ * can be reverted.
  *
- * Each triggered match may result in one or more constraint occurrences
- * to be deactivated/terminated.
+ * The main (and only) example of such event is an occurrence activation and the
+ * corresponding observer reactivates occurrence on changes of logical variables
+ * used as its arguments.
  *
- * An activated or deactivated constraint occurrence updates the dispatching front --
- * an object that maintains a search tree for possible rule matches. 
- * 
  * @author Fedor Isakov
  */
 

reactor/Core/src/jetbrains/mps/logic/reactor/core/internal/StateFrameStack.kt

@@ -21,6 +21,17 @@ import jetbrains.mps.logic.reactor.logical.Logical
 import java.util.*
 
 
+/**
+ * A [StateFrameStack] maintains a stack of [StateFrame]s capturing processing
+ * state related to logical variable observers. The top [StateFrame] contains
+ * the current relevant set of [LogicalObserver]s. Events corresponding to
+ * adding and removing observers are forwarded to the top frame.
+ *
+ * Frames are added on events which could require reverting processing state to
+ * the point before them, which can be achieved by simply dropping a frame and
+ * thus dropping all added observers.
+ */
+
 internal open class StateFrameStack() : ProcessingState, LogicalObserver
 {
     // invariant: never empty