Add docs

9 files changed, 35 insertions, 0 deletions

diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
index d1e3c4bb..02264a62 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
@@ -4,6 +4,17 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
+/**
+ * Pop a receiver and arguments from the stack and call the receiver with those arguments.
+ *
+ * <p>Specifically, the values should have been pushed onto the stack in the following order:</p>
+ *
+ * <ul>
+ *     <li>The receiver i.e. the function to be called.</li>
+ *     <li>The positional arguments, from left to right.</li>
+ *     <li>The named arguments, in the same order as <code>namedArgNames</code>.</li>
+ * </ul>
+ */
 public record CallInstruction(
     int positionalArgCount,
     List<String> namedArgNames,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
index 379f1f68..1c4a6ab5 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
@@ -5,6 +5,9 @@ import org.shedlang.compiler.sources.Source;
 import java.util.List;
 import java.util.Set;
 
+/**
+ * Push a function value onto the stack with the given definition.
+ */
 public record DefineFunctionInstruction(
     String name,
     List<Param> positionalParams,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
index 6efd3c03..91b74c45 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
@@ -2,5 +2,8 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Pop a value from the stack and discard it.
+ */
 public record DiscardInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
index b7656ed3..ef4a923f 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
@@ -2,5 +2,8 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Load the local with the given name and push it onto the stack.
+ */
 public record LocalLoadInstruction(String name, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
index 038e3d29..eb0331e1 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
@@ -2,5 +2,8 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Pop a value from the stack and store it as the local with the given name.
+ */
 public record LocalStoreInstruction(String name, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
index 0d9ad6b4..59a34413 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
@@ -2,6 +2,9 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Push a boolean onto the stack.
+ */
 public record PushBoolInstruction(
     boolean value,
     Source source
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
index aa73d817..7a417bb6 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
@@ -4,5 +4,8 @@ import org.shedlang.compiler.sources.Source;
 
 import java.math.BigInteger;
 
+/**
+ * Push an integer onto the stack.
+ */
 public record PushIntInstruction(BigInteger value, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
index 364e5444..9322b72f 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
@@ -2,5 +2,8 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Push a string onto the stack.
+ */
 public record PushStringInstruction(String value, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
index c7c306c4..15a3560f 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
@@ -2,5 +2,8 @@ package org.shedlang.compiler.stackir.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
+/**
+ * Push the unit value onto the stack.
+ */
 public record PushUnitInstruction(Source source) implements Instruction {
 }