Adding Javadoc to State manipulation nodes

engine/runtime/src/main/java/org/enso/interpreter/runtime/state/GetStateNode.java

@@ -12,6 +12,7 @@
 import org.enso.interpreter.runtime.EnsoContext;
 import org.enso.interpreter.runtime.error.PanicException;
 
+/** Use this node to manipulate {@link State}. */
 @BuiltinMethod(
     type = "State",
     name = "get",
@@ -34,6 +35,13 @@ final Object execute(Object key) {
     return executeGet(key);
   }
 
+  /**
+   * Reads value associated with a key from the {@link State}.
+   *
+   * @param key the key to read the value for
+   * @return the value associated with the key
+   * @throws {@link PanicException} when there is no such key in the {@link State}
+   */
   public abstract Object executeGet(Object key);
 
   final State state() {

engine/runtime/src/main/java/org/enso/interpreter/runtime/state/PutStateNode.java

@@ -11,6 +11,7 @@
 import org.enso.interpreter.runtime.EnsoContext;
 import org.enso.interpreter.runtime.error.PanicException;
 
+/** Use this node to manipulate {@link State}. */
 @BuiltinMethod(
     type = "State",
     name = "put",
@@ -28,6 +29,14 @@ final Object execute(Object key, Object newState) {
     return executePut(key, newState);
   }
 
+  /**
+   * Updates a value in the {@link State}. The node never defines new state key!
+   *
+   * @param key the key in the state as defined by the {@link RunStateNode#execute}
+   * @param newState new value to associate with the key
+   * @return the {@code newState} value
+   * @throws {@link PanicException} if the key hasn't been defined in the {@link State} yet
+   */
   public abstract Object executePut(Object key, Object newState);
 
   final State state() {

engine/runtime/src/main/java/org/enso/interpreter/runtime/state/RunStateNode.java

@@ -19,6 +19,7 @@
 import org.enso.interpreter.runtime.data.Type;
 import org.enso.interpreter.runtime.error.PanicException;
 
+/** Use this node to manipulate {@link State}. */
 @BuiltinMethod(
     type = "State",
     name = "run",
@@ -38,8 +39,18 @@ public static RunStateNode getUncached() {
     return RunStateNodeGen.getUncached();
   }
 
+  /**
+   * Defines new value in {@link State}. Use {@link PutStateNode} to change the value inside of the
+   * {@code computation} and {@link GetStateNode} to read the value.
+   *
+   * @param frame the execution frame to pass to {@code computation}
+   * @param key the key to define in the {@link State}
+   * @param value the value to assign to the state
+   * @param computation the computation to perform the the {@code key} being in the {@link State}
+   * @return result of {@code computation}
+   */
   public abstract Object execute(
-      VirtualFrame frame, Object key, Object local_state, @Suspend Object computation);
+      VirtualFrame frame, Object key, Object value, @Suspend Object computation);
 
   final State state() {
     return EnsoContext.get(this).currentState();

engine/runtime/src/main/java/org/enso/interpreter/runtime/state/State.java

@@ -8,10 +8,15 @@
  * Represents a <em>thread local</em> state associated with execution of the program. Use nodes:
  *
  * <ul>
-*   <li>{@link RunStateNode} to run execution with some state
+ *   <li>{@link RunStateNode} to run execution with some state
  *   <li>{@link GetStateNode} to read value in a state
  *   <li>{@link PutStateNode} to change value in a state
  * </ul>
+ *
+ * First and foremost use {@link RunStateNode} to define a new key in the {@link State}. Then use
+ * the other nodes to read and update the value. The key and its value is removed from the {@link
+ * State} when {@link RunStateNode#execute} method returns. Current state can be obtained by {@link
+ * EnsoContext#currentState} method.
  */
 public final class State {
   private static final EnsoContext.Extra<Shape> ROOT_STATE_SHAPE =