Add hobgoblin definitions for Patio

29 files changed, 609 insertions, 104 deletions

diff --git a/hobgoblin/src/patio.hob b/hobgoblin/src/patio.hob
index e69de29b..5a2d0734 100644
--- a/hobgoblin/src/patio.hob
+++ b/hobgoblin/src/patio.hob
@@ -0,0 +1,84 @@
+import {Source} from ./sources;
+import {PatioInstruction} from ./patio/instructions;
+import {PatioDataLayout, PatioDataValue, PatioType} from ./patio/types;
+
+// == Compilation units ==
+
+struct PatioCompilationUnit {
+  field elements: List[PatioCompilationUnitElement];
+  field source: Source;
+}
+
+// == Compilation unit elements ==
+
+sum PatioCompilationUnitElement {
+  variant PatioDataElementImmutableDefinition;
+  variant PatioDataElementMutableDeclaration;
+  variant PatioDataElementMutableDefinition;
+  variant PatioExceptionTypeDefinition;
+  variant PatioFunctionDeclaration;
+  variant PatioFunctionDefinition;
+}
+
+struct PatioDataElementImmutableDefinition {
+    field name: String;
+    field visibility: PatioVisibility;
+    field value: PatioDataValue;
+    field source: Source;
+}
+
+struct PatioDataElementMutableDeclaration {
+    field name: String;
+    field layout: PatioDataLayout;
+    field source: Source;
+}
+
+struct PatioDataElementMutableDefinition {
+    field name: String;
+    field visibility: PatioVisibility;
+    field initialValue: PatioDataValue;
+    field source: Source;
+}
+
+struct PatioExceptionTypeDefinition {
+    field name: String;
+    field valueType: PatioType;
+    field source: Source;
+}
+
+struct PatioFunctionDeclaration {
+    field name: String;
+    field params: List[PatioLocal];
+    field returnTypes: List[PatioType];
+    field source: Source;
+}
+
+struct PatioFunctionDefinition {
+    field name: String;
+    field visibility: PatioVisibility;
+    field locals: List[PatioLocal];
+    field returnTypes: List[PatioType];
+    field body: List[PatioInstruction];
+    field source: Source;
+}
+
+// == Visibility ==
+
+enum PatioVisibility {
+    variant private;
+    variant public;
+}
+
+// == Locals ==
+
+struct PatioLocal {
+    field name: String;
+    field type: PatioType;
+    field localType: PatioLocalType;
+}
+
+enum PatioLocalType {
+    variant param;
+    variant val;
+    variant var;
+}
diff --git a/hobgoblin/src/patio/instructions.hob b/hobgoblin/src/patio/instructions.hob
new file mode 100644
index 00000000..c6f33976
--- /dev/null
+++ b/hobgoblin/src/patio/instructions.hob
@@ -0,0 +1,253 @@
+import {Source} from ../sources;
+import {PatioLocalRef, PatioOperand} from ./operands;
+import {PatioDataLayout} from ./types;
+
+sum PatioInstruction {
+    variant PatioBlock;
+    variant PatioBoolToInt;
+    variant PatioCall;
+    variant PatioCallPointer;
+    variant PatioDataPtrToInt;
+    variant PatioIf;
+    variant PatioIntAdd;
+    variant PatioIntEquals;
+    variant PatioIntNotEqual;
+    variant PatioIntSub;
+    variant PatioIntToBool;
+    variant PatioIntToDataPtr;
+    variant PatioLocalStore;
+    variant PatioLoop;
+    variant PatioLoopBreak;
+    variant PatioLoopContinue;
+    variant PatioMemoryLoad;
+    variant PatioMemoryStore;
+    variant PatioReturn;
+    variant PatioSwitch;
+    variant PatioThrow;
+    variant PatioTry;
+    variant PatioUnreachable;
+    variant PatioVarLoad;
+    variant PatioVarStore;
+}
+
+/// Execute the instructions in the body of the block. The results may be used in
+/// the parent scope, but any other variables (as distinct from values) are no
+/// longer in use.
+struct PatioBlock {
+    field body: List[PatioInstruction];
+    field results: List[PatioOperand];
+    field source: Source;
+}
+
+struct PatioBoolToInt {
+    field destination: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// Call the function with the given name, and store the returned values in the
+/// destination locals.
+struct PatioCall {
+    field destinations: List[PatioLocalRef];
+    field functionName: String;
+    field args: List[PatioOperand];
+    field source: Source;
+}
+
+/// Call the function pointed to by the function pointer with the given
+/// arguments, and store the returned values in the destination locals.
+struct PatioCallPointer {
+    field destinations: List[PatioLocalRef];
+    field functionPointer: PatioOperand;
+    field args: List[PatioOperand];
+    field source: Source;
+}
+
+struct PatioDataPtrToInt {
+    field destination: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// If the condition is true, execute the instructions in the "true" body,
+/// otherwise execute the instructions in the "false" body.
+///
+/// Each block must have the same number of results as destinations. Each result is
+/// assigned to the destination with the same index.
+struct PatioIf {
+    field destinations: List[PatioLocalRef];
+    field condition: PatioOperand;
+    field trueBody: PatioBlock;
+    field falseBody: PatioBlock;
+    field source: Source;
+}
+
+struct PatioIntAdd {
+    field destination: PatioLocalRef;
+    field left: PatioOperand;
+    field right: PatioOperand;
+    field source: Source;
+}
+
+struct PatioIntEquals {
+    field destination: PatioLocalRef;
+    field left: PatioOperand;
+    field right: PatioOperand;
+    field source: Source;
+}
+
+/// Compare the left and right operands. If they are equal, store false in the
+/// destination, otherwise store true in the destination.
+struct PatioIntNotEqual {
+    field destination: PatioLocalRef;
+    field left: PatioOperand;
+    field right: PatioOperand;
+    field source: Source;
+}
+
+/// Calculate the left operand minus the right operand, and store the result in
+/// the destination.
+struct PatioIntSub {
+    field destination: PatioLocalRef;
+    field left: PatioOperand;
+    field right: PatioOperand;
+    field source: Source;
+}
+
+struct PatioIntToBool {
+    field destination: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+struct PatioIntToDataPtr {
+    field destination: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// Store the given value in the destination local.
+struct PatioLocalStore {
+    field destination: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// Execute the body. The `continue` instruction can jump back to the
+/// start of the body. The `break` instruction can jump to the end of
+/// the body.
+struct PatioLoop {
+    field body: List[PatioInstruction];
+    field source: Source;
+}
+
+/// Jump to the end of the enclosing `loop` instruction's body.
+struct PatioLoopBreak {
+    field source: Source;
+}
+
+/// Jump to the start of the enclosing `loop` instruction's body.
+struct PatioLoopContinue {
+    field source: Source;
+}
+
+/// Load the value at the given offset from the given pointer and store it in the
+/// destination local.
+struct PatioMemoryLoad {
+    field destination: PatioLocalRef;
+    field pointer: PatioOperand;
+    field layout: PatioDataLayout;
+    field elementOffsets: List[Int32];
+    field source: Source;
+}
+
+/// Store the given value at the given offset from the given pointer.
+struct PatioMemoryStore {
+    field pointer: PatioOperand;
+    field layout: PatioDataLayout;
+    field elementOffsets: List[Int32];
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// Return with the given values from the current function.
+struct PatioReturn {
+    field values: List[PatioOperand];
+    field source: Source;
+}
+
+/// Find a case with a value matching that of the instruction's value. If such a
+/// case is found, execute the body of that case, otherwise execute the default
+/// body.
+///
+/// Each block must have the same number of results as destinations. Each result
+/// is assigned to the destination with the same index.
+struct PatioSwitch {
+    field destinations: List[PatioLocalRef];
+    field value: PatioOperand;
+    field cases: List[PatioSwitchCase];
+    field defaultBody: PatioBlock;
+    field source: Source;
+}
+
+struct PatioSwitchCase {
+    field value: Int32;
+    field body: PatioBlock;
+    field source: Source;
+}
+
+/// Search the stack for an exception handler with a catch clause matching the
+/// thrown exception type. Unwind the stack up to and including this exception
+/// handler, and run the body of the catch clause. If no such exception handler
+/// is found, the process should abort.
+struct PatioThrow {
+    field exceptionTypeName: String;
+    field value: PatioOperand;
+    field source: Source;
+}
+
+/// Push an exception handler with the given catch clauses onto the control flow
+/// stack, and then execute the instructions in its body.
+///
+/// If the exception handler catches an exception, the body of the corresponding
+/// is executed instead.
+///
+/// Each block (that is, the body of the try and the body of each catch clause)
+/// must have the same number of results as destinations. Each result is assigned to
+/// the destination with the same index.
+struct PatioTry {
+    field destinations: List[PatioLocalRef];
+    field catchClauses: List[PatioCatchClause];
+    field body: PatioBlock;
+    field source: Source;
+}
+
+/// A catch clause can accept an exception of a given type. If executed, it will
+/// stored the value of the exception in the given destination, and then execute the
+/// body.
+struct PatioCatchClause {
+    field exceptionTypeName: String;
+    field destination: PatioLocalRef;
+    field body: PatioBlock;
+    field source: Source;
+}
+
+/// Unreachable instructions have undefined behaviour, and are used to indicate
+/// that an instruction sequence is unreachable.
+struct PatioUnreachable {
+    field source: Source;
+}
+
+/// Load the value from the given var and store it in the destination local.
+struct PatioVarLoad {
+    field destination: PatioLocalRef;
+    field var: PatioLocalRef;
+    field source: Source;
+}
+
+/// Store the given value in the destination var.
+struct PatioVarStore {
+    field var: PatioLocalRef;
+    field value: PatioOperand;
+    field source: Source;
+}
diff --git a/hobgoblin/src/patio/operands.hob b/hobgoblin/src/patio/operands.hob
new file mode 100644
index 00000000..5a8769f7
--- /dev/null
+++ b/hobgoblin/src/patio/operands.hob
@@ -0,0 +1,39 @@
+import {PatioDataPtrValue, PatioIntValue} from ./values;
+
+sum PatioOperand {
+    variant PatioLocalRef;
+    variant PatioBoolConst;
+    variant PatioByteConst;
+    variant PatioDataPtrConst;
+    variant PatioFunctionPtrConst;
+    variant PatioInt32Const;
+    variant PatioIntConst;
+}
+
+struct PatioLocalRef {
+    field name: String;
+}
+
+struct PatioBoolConst {
+    field value: Bool;
+}
+
+struct PatioByteConst {
+    field value: Int8;
+}
+
+struct PatioDataPtrConst {
+    field value: PatioDataPtrValue;
+}
+
+struct PatioFunctionPtrConst {
+    field name: String;
+}
+
+struct PatioInt32Const {
+    field value: PatioIntValue;
+}
+
+struct PatioIntConst {
+    field value: PatioIntValue;
+}
diff --git a/hobgoblin/src/patio/types.hob b/hobgoblin/src/patio/types.hob
new file mode 100644
index 00000000..3155e576
--- /dev/null
+++ b/hobgoblin/src/patio/types.hob
@@ -0,0 +1,123 @@
+import {PatioDataPtrValue, PatioIntValue} from ./values;
+
+// == Types ==
+
+sum PatioType {
+    variant PatioBoolType;
+    variant PatioByteType;
+    variant PatioDataPtrType;
+    variant PatioFunctionPtrType;
+    variant PatioInt32Type;
+    variant PatioIntType;
+}
+
+struct PatioBoolType {
+    singleton;
+}
+
+struct PatioByteType {
+    singleton;
+}
+
+struct PatioDataPtrType {
+    singleton;
+}
+
+struct PatioFunctionPtrType {
+    singleton;
+}
+
+struct PatioInt32Type {
+    singleton;
+}
+
+struct PatioIntType {
+    singleton;
+}
+
+// == Data layouts ==
+
+sum PatioDataLayout {
+    variant PatioDataLayoutArray;
+    variant PatioDataLayoutBool;
+    variant PatioDataLayoutByte;
+    variant PatioDataLayoutDataPtr;
+    variant PatioDataLayoutFunctionPtr;
+    variant PatioDataLayoutInt;
+    variant PatioDataLayoutInt32;
+    variant PatioDataLayoutStruct;
+}
+
+struct PatioDataLayoutArray {
+    field element: PatioDataLayout;
+    field size: Int32;
+}
+
+struct PatioDataLayoutBool {
+    singleton;
+}
+
+struct PatioDataLayoutByte {
+    singleton;
+}
+
+struct PatioDataLayoutDataPtr {
+    singleton;
+}
+
+struct PatioDataLayoutFunctionPtr {
+    singleton;
+}
+
+struct PatioDataLayoutInt {
+    singleton;
+}
+
+struct PatioDataLayoutInt32 {
+    singleton;
+}
+
+struct PatioDataLayoutStruct {
+    field elements: List[PatioDataLayout];
+}
+
+// == Data values ==
+
+sum PatioDataValue {
+    variant PatioDataValueArray;
+    variant PatioDataValueBool;
+    variant PatioDataValueByte;
+    variant PatioDataValueDataPtr;
+    variant PatioDataValueInt;
+    variant PatioDataValueInt32;
+    variant PatioDataValueStruct;
+}
+
+struct PatioDataValueArray {
+    field elementLayout: PatioDataLayout;
+    field elements: List[PatioDataValue];
+}
+
+struct PatioDataValueBool {
+    field value: Bool;
+}
+
+struct PatioDataValueByte {
+    field value: Int8;
+}
+
+struct PatioDataValueDataPtr {
+    field value: PatioDataPtrValue;
+}
+
+struct PatioDataValueInt {
+    field value: PatioIntValue;
+}
+
+struct PatioDataValueInt32 {
+    field value: PatioIntValue;
+}
+
+struct PatioDataValueStruct {
+    field elements: List[PatioDataValue];
+}
diff --git a/hobgoblin/src/patio/values.hob b/hobgoblin/src/patio/values.hob
new file mode 100644
index 00000000..0e14cf35
--- /dev/null
+++ b/hobgoblin/src/patio/values.hob
@@ -0,0 +1,43 @@
+import {PatioDataLayout} from ./types;
+
+// == Data ptr values ==
+
+sum PatioDataPtrValue {
+    variant PatioDataPtrValueDataElement;
+    variant PatioDataPtrValueNull;
+}
+
+struct PatioDataPtrValueDataElement {
+    field name: String;
+}
+
+struct PatioDataPtrValueNull {
+}
+
+// == Int values ==
+
+/// An int value that is a constant in the compiled program, but may differ
+/// across targets.
+sum PatioIntValue {
+    variant PatioIntValueByteOffsetOf;
+    variant PatioIntValueByteSizeOf;
+    variant PatioIntValueLiteral;
+}
+
+/// The offset, in bytes, of an offset in a data layout.
+struct PatioIntValueByteOffsetOf {
+    field layout: PatioDataLayout;
+    field elementOffsets: List[Int32];
+}
+
+/// The size, in bytes, of a data layout.
+struct PatioIntValueByteSizeOf {
+    field layout: PatioDataLayout;
+}
+
+/// An int value that is the same across all targets.
+struct PatioIntValueLiteral {
+    field value: Int32;
+}
+
+
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioBlock.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioBlock.java
index 5858159f..fd7932b6 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioBlock.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioBlock.java
@@ -6,11 +6,9 @@ import org.shedlang.compiler.util.Lists;
 
 import java.util.List;
 
-/**
- * Execute the instructions in the body of the block. The results may be used in
- * the parent scope, but any other variables (as distinct from values) are no
- * longer in use.
- */
+/// Execute the instructions in the body of the block. The results may be used in
+/// the parent scope, but any other variables (as distinct from values) are no
+/// longer in use.
 public record PatioBlock(
     List<PatioInstruction> body,
     List<? extends PatioOperand> results,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCall.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCall.java
index c430b732..02159902 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCall.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCall.java
@@ -6,10 +6,8 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Call the function with the given name, and store the returned values in the
- * destination locals.
- */
+/// Call the function with the given name, and store the returned values in the
+/// destination locals.
 public record PatioCall(
     List<PatioLocalRef> destinations,
     String functionName,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCallPointer.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCallPointer.java
index 80aa6a3a..f8823b38 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCallPointer.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCallPointer.java
@@ -6,10 +6,8 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Call the function pointed to by the function pointer with the given
- * arguments, and store the returned values in the destination locals.
- */
+/// Call the function pointed to by the function pointer with the given
+/// arguments, and store the returned values in the destination locals.
 public record PatioCallPointer(
     List<PatioLocalRef> destinations,
     PatioOperand functionPointer,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCatchClause.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCatchClause.java
index edbeb3bb..178663bf 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioCatchClause.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioCatchClause.java
@@ -3,11 +3,9 @@ package org.shedlang.compiler.patio.instructions;
 import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * A catch clause can accept an exception of a given type. If executed, it will
- * stored the value of the exception in the given destination, and then execute the
- * body.
- */
+/// A catch clause can accept an exception of a given type. If executed, it will
+/// stored the value of the exception in the given destination, and then execute the
+/// body.
 public record PatioCatchClause(
     String exceptionTypeName,
     PatioLocalRef destination,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIf.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIf.java
index af6bdac9..9e5fe50f 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIf.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIf.java
@@ -6,13 +6,11 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * If the condition is true, execute the instructions in the "true" body,
- * otherwise execute the instructions in the "false" body.
- * <p>
- * Each block must have the same number of results as destinations. Each result is
- * assigned to the destination with the same index.
- */
+/// If the condition is true, execute the instructions in the "true" body,
+/// otherwise execute the instructions in the "false" body.
+///
+/// Each block must have the same number of results as destinations. Each result is
+/// assigned to the destination with the same index.
 public record PatioIf(
     List<PatioLocalRef> destinations,
     PatioOperand condition,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntNotEqual.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntNotEqual.java
index b00e0f6d..d1d987f9 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntNotEqual.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntNotEqual.java
@@ -4,10 +4,8 @@ import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.patio.operands.PatioOperand;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Compare the left and right operands. If they are equal, store false in the
- * destination, otherwise store true in the destination.
- */
+/// Compare the left and right operands. If they are equal, store false in the
+/// destination, otherwise store true in the destination.
 public record PatioIntNotEqual(
     PatioLocalRef destination,
     PatioOperand left,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntSub.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntSub.java
index 24f41107..bf6950c8 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntSub.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioIntSub.java
@@ -4,10 +4,8 @@ import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.patio.operands.PatioOperand;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Calculate the left operand minus the right operand, and store the result in
- * the destination.
- */
+/// Calculate the left operand minus the right operand, and store the result in
+/// the destination.
 public record PatioIntSub(
     PatioLocalRef destination,
     PatioOperand left,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLocalStore.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLocalStore.java
index c72d0252..a531c247 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLocalStore.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLocalStore.java
@@ -4,9 +4,7 @@ import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.patio.operands.PatioOperand;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Store the given value in the destination local.
- */
+/// Store the given value in the destination local.
 public record PatioLocalStore(
     PatioLocalRef destination,
     PatioOperand value,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoop.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoop.java
index 650b1108..5089effb 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoop.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoop.java
@@ -4,11 +4,9 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Execute the body. The <code>continue</code> instruction can jump back to the
- * start of the body. The <code>break</code> instruction can jump to the end of
- * the body.
- */
+/// Execute the body. The `continue` instruction can jump back to the
+/// start of the body. The `break` instruction can jump to the end of
+/// the body.
 public record PatioLoop(
     List<PatioInstruction> body,
     Source source
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopBreak.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopBreak.java
index bad43e15..ae27cf98 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopBreak.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopBreak.java
@@ -2,9 +2,7 @@ package org.shedlang.compiler.patio.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Jump to the end of the enclosing <code>loop</code> instruction's body.
- */
+/// Jump to the end of the enclosing `loop` instruction's body.
 public record PatioLoopBreak(Source source) implements PatioInstruction {
     @Override
     public boolean isBlockTerminator() {
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopContinue.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopContinue.java
index 41dcc6fd..83517e83 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopContinue.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioLoopContinue.java
@@ -2,9 +2,7 @@ package org.shedlang.compiler.patio.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Jump to the start of the enclosing <code>loop</code> instruction's body.
- */
+/// Jump to the start of the enclosing `loop` instruction's body.
 public record PatioLoopContinue(Source source) implements PatioInstruction {
     @Override
     public boolean isBlockTerminator() {
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryLoad.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryLoad.java
index 1262d040..5d4642a0 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryLoad.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryLoad.java
@@ -7,10 +7,8 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Load the value at the given offset from the given pointer and store it in the
- * destination local.
- */
+/// Load the value at the given offset from the given pointer and store it in the
+/// destination local.
 public record PatioMemoryLoad(
     PatioLocalRef destination,
     PatioOperand pointer,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryStore.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryStore.java
index cfcdf9a7..68136b3b 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryStore.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioMemoryStore.java
@@ -6,9 +6,7 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Store the given value at the given offset from the given pointer.
- */
+/// Store the given value at the given offset from the given pointer.
 public record PatioMemoryStore(
     PatioOperand pointer,
     PatioDataLayout layout,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioReturn.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioReturn.java
index c7cfbead..69d294c2 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioReturn.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioReturn.java
@@ -5,9 +5,7 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Return with the given values from the current function.
- */
+/// Return with the given values from the current function.
 public record PatioReturn(List<PatioOperand> values, Source source) implements PatioInstruction {
     @Override
     public boolean isBlockTerminator() {
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitch.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitch.java
index 0b11e9d0..28923ea7 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitch.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitch.java
@@ -6,24 +6,19 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Find a case with a value matching that of the instruction's value. If such a
- * case is found, execute the body of that case, otherwise execute the default
- * body.
- * <p>
- * Each block must have the same number of results as destinations. Each result
- * is assigned to the destination with the same index.
- */
+/// Find a case with a value matching that of the instruction's value. If such a
+/// case is found, execute the body of that case, otherwise execute the default
+/// body.
+///
+/// Each block must have the same number of results as destinations. Each result
+/// is assigned to the destination with the same index.
 public record PatioSwitch(
     List<PatioLocalRef> destinations,
     PatioOperand value,
-    List<Case> cases,
+    List<PatioSwitchCase> cases,
     PatioBlock defaultBody,
     Source source
 ) implements PatioInstruction {
-    public record Case(int value, PatioBlock body, Source source) {
-    }
-
     @Override
     public boolean isBlockTerminator() {
         return true;
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitchCase.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitchCase.java
new file mode 100644
index 00000000..c446476e
--- /dev/null
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioSwitchCase.java
@@ -0,0 +1,6 @@
+package org.shedlang.compiler.patio.instructions;
+
+import org.shedlang.compiler.sources.Source;
+
+public record PatioSwitchCase(int value, PatioBlock body, Source source) {
+}
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioThrow.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioThrow.java
index 86a3afbb..95b9dd7c 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioThrow.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioThrow.java
@@ -3,12 +3,10 @@ package org.shedlang.compiler.patio.instructions;
 import org.shedlang.compiler.patio.operands.PatioOperand;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Search the stack for an exception handler with a catch clause matching the
- * thrown exception type. Unwind the stack up to and including this exception
- * handler, and run the body of the catch clause. If no such exception handler
- * is found, the process should abort.
- */
+/// Search the stack for an exception handler with a catch clause matching the
+/// thrown exception type. Unwind the stack up to and including this exception
+/// handler, and run the body of the catch clause. If no such exception handler
+/// is found, the process should abort.
 public record PatioThrow(
     String exceptionTypeName,
     PatioOperand value,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioTry.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioTry.java
index 893750a6..95368141 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioTry.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioTry.java
@@ -5,17 +5,15 @@ import org.shedlang.compiler.sources.Source;
 
 import java.util.List;
 
-/**
- * Push an exception handler with the given catch clauses onto the control flow
- * stack, and then execute the instructions in its body.
- * <p>
- * If the exception handler catches an exception, the body of the corresponding
- * is executed instead.
- * <p>
- * Each block (that is, the body of the try and the body of each catch clause)
- * must have the same number of results as destinations. Each result is assigned to
- * the destination with the same index.
- */
+/// Push an exception handler with the given catch clauses onto the control flow
+/// stack, and then execute the instructions in its body.
+///
+/// If the exception handler catches an exception, the body of the corresponding
+/// is executed instead.
+///
+/// Each block (that is, the body of the try and the body of each catch clause)
+/// must have the same number of results as destinations. Each result is assigned to
+/// the destination with the same index.
 public record PatioTry(
     List<PatioLocalRef> destinations,
     List<PatioCatchClause> catchClauses,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioUnreachable.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioUnreachable.java
index 1550105c..1ccb6342 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioUnreachable.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioUnreachable.java
@@ -2,10 +2,8 @@ package org.shedlang.compiler.patio.instructions;
 
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Unreachable instructions have undefined behaviour, and are used to indicate
- * that an instruction sequence is unreachable.
- */
+/// Unreachable instructions have undefined behaviour, and are used to indicate
+/// that an instruction sequence is unreachable.
 public record PatioUnreachable(Source source) implements PatioInstruction {
     @Override
     public boolean isBlockTerminator() {
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarLoad.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarLoad.java
index 02117bc6..b60007bb 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarLoad.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarLoad.java
@@ -3,9 +3,7 @@ package org.shedlang.compiler.patio.instructions;
 import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Load the value from the given var and store it in the destination local.
- */
+/// Load the value from the given var and store it in the destination local.
 public record PatioVarLoad(
     PatioLocalRef destination,
     PatioLocalRef var,
diff --git a/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarStore.java b/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarStore.java
index dd345af2..80c4ef60 100644
--- a/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarStore.java
+++ b/src/main/java/org/shedlang/compiler/patio/instructions/PatioVarStore.java
@@ -4,9 +4,7 @@ import org.shedlang.compiler.patio.operands.PatioLocalRef;
 import org.shedlang.compiler.patio.operands.PatioOperand;
 import org.shedlang.compiler.sources.Source;
 
-/**
- * Store the given value in the destination var.
- */
+/// Store the given value in the destination var.
 public record PatioVarStore(
     PatioLocalRef var,
     PatioOperand value,
diff --git a/src/main/java/org/shedlang/compiler/patio/serialization/PatioToFlatbuffers.java b/src/main/java/org/shedlang/compiler/patio/serialization/PatioToFlatbuffers.java
index c3df7f0b..1f2e34c8 100644
--- a/src/main/java/org/shedlang/compiler/patio/serialization/PatioToFlatbuffers.java
+++ b/src/main/java/org/shedlang/compiler/patio/serialization/PatioToFlatbuffers.java
@@ -1729,7 +1729,7 @@ public class PatioToFlatbuffers {
 
     private static int serializeSwitchCase(
         FlatBufferBuilder builder,
-        PatioSwitch.Case case_,
+        PatioSwitchCase case_,
         Source parentSource
     ) {
         var sourceFbs = SourceToFlatbuffers.serializeSource(
@@ -1747,7 +1747,7 @@ public class PatioToFlatbuffers {
         return PatioSwitchCaseFbs.endPatioSwitchCaseFbs(builder);
     }
 
-    private static PatioSwitch.Case deserializeSwitchCase(
+    private static PatioSwitchCase deserializeSwitchCase(
         PatioSwitchCaseFbs caseFbs,
         Source parentSource
     ) {
@@ -1758,7 +1758,7 @@ public class PatioToFlatbuffers {
 
         var body = deserializeBlock(caseFbs.body(), source);
 
-        return new PatioSwitch.Case((int) caseFbs.value(), body, source);
+        return new PatioSwitchCase((int) caseFbs.value(), body, source);
     }
 
     public static int serializeThrow(
diff --git a/src/main/java/org/shedlang/compiler/shidtopatio/ShidToPatio.java b/src/main/java/org/shedlang/compiler/shidtopatio/ShidToPatio.java
index 88d56cf6..062375eb 100644
--- a/src/main/java/org/shedlang/compiler/shidtopatio/ShidToPatio.java
+++ b/src/main/java/org/shedlang/compiler/shidtopatio/ShidToPatio.java
@@ -821,7 +821,7 @@ public class ShidToPatio {
                     context
                 );
 
-                var cases = new ArrayList<PatioSwitch.Case>();
+                var cases = new ArrayList<PatioSwitchCase>();
 
                 for (var shidCase : switch_.cases()) {
                     var bodyResult = generateBlock(
@@ -831,7 +831,7 @@ public class ShidToPatio {
                     var body = bodyResult.value();
                     context = bodyResult.context();
 
-                    cases.add(new PatioSwitch.Case(
+                    cases.add(new PatioSwitchCase(
                         context.structTag(shidCase.caseType()),
                         body,
                         shidCase.source()
diff --git a/src/test/java/org/shedlang/compiler/patio/instructions/Patio.java b/src/test/java/org/shedlang/compiler/patio/instructions/Patio.java
index ec332d94..893ce60e 100644
--- a/src/test/java/org/shedlang/compiler/patio/instructions/Patio.java
+++ b/src/test/java/org/shedlang/compiler/patio/instructions/Patio.java
@@ -326,14 +326,14 @@ public class Patio {
     public static PatioInstruction switch_(
         List<PatioLocalRef> destinations,
         PatioOperand value,
-        List<PatioSwitch.Case> cases,
+        List<PatioSwitchCase> cases,
         PatioBlock defaultBody
     ) {
         return new PatioSwitch(destinations, value, cases, defaultBody, Sources.NULL);
     }
 
-    public static PatioSwitch.Case switchCase(int value, PatioBlock body) {
-        return new PatioSwitch.Case(value, body, Sources.NULL);
+    public static PatioSwitchCase switchCase(int value, PatioBlock body) {
+        return new PatioSwitchCase(value, body, Sources.NULL);
     }
 
     public static PatioInstruction throw_(String exceptionTypeName, PatioOperand value) {