From 3d74da69beaa13c3cb14aa5dbdd6c552fe40bb14 Mon Sep 17 00:00:00 2001
From: Jaroslav Tulach <jaroslav.tulach@enso.org>
Date: Fri, 21 Feb 2025 15:46:50 +0100
Subject: [PATCH] Adding Javadoc to State manipulation nodes

---
 .../interpreter/runtime/state/GetStateNode.java     |  8 ++++++++
 .../interpreter/runtime/state/PutStateNode.java     |  9 +++++++++
 .../interpreter/runtime/state/RunStateNode.java     | 13 ++++++++++++-
 .../org/enso/interpreter/runtime/state/State.java   |  7 ++++++-
 4 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/GetStateNode.java b/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/GetStateNode.java
index 11efc91239d3..39bc67de633b 100644
--- a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/GetStateNode.java
+++ b/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() {
diff --git a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/PutStateNode.java b/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/PutStateNode.java
index 3333cbaf4128..c1341a2c9bd3 100644
--- a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/PutStateNode.java
+++ b/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() {
diff --git a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/RunStateNode.java b/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/RunStateNode.java
index 0e8107c408a5..97c0bc8215bb 100644
--- a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/RunStateNode.java
+++ b/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();
diff --git a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/State.java b/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/State.java
index a030691cfa37..ac9770c7c816 100644
--- a/engine/runtime/src/main/java/org/enso/interpreter/runtime/state/State.java
+++ b/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 =