chore: Improve AST nodes documentation

vadl/main/vadl/ast/Expr.java

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText : © 2025 TU Wien <vadl@tuwien.ac.at>
+// SPDX-FileCopyrightText : © 2025-2026 TU Wien <vadl@tuwien.ac.at>
 // SPDX-License-Identifier: GPL-3.0-or-later
 //
 // This program is free software: you can redistribute it and/or modify
@@ -152,6 +152,11 @@ interface ExprVisitor<R> {
   R visit(ResourceReferenceExression expr);
 }
 
+/**
+ * A reference to a named entity in the specification.
+ * The {@link #target} field is resolved during symbol resolving to point to the
+ * referenced {@link Node}.
+ */
 final class Identifier extends Expr implements IsId, IdentifierOrPlaceholder {
   String name;
   SourceLocation loc;
@@ -484,6 +489,11 @@ public int hashCode() {
   }
 }
 
+/**
+ * A unary expression using prefix notation.
+ * Supported operators are {@code -} (negation), {@code !} (logical not),
+ * and {@code ~} (bitwise complement).
+ */
 class UnaryExpr extends Expr {
   IsUnOp operator;
   @Child
@@ -559,6 +569,11 @@ public int hashCode() {
   }
 }
 
+/**
+ * A positive integer literal in decimal form.
+ * Digits can be separated with {@code '} for readability (e.g. {@code 1'000'000}).
+ * Negative numeric literals are represented by applying the negation {@link UnaryExpr}.
+ */
 class IntegerLiteral extends Expr {
   String token;
   BigInteger number;
@@ -620,6 +635,9 @@ public int hashCode() {
   }
 }
 
+/**
+ * A wildcard literal ({@code *}) used as a catch-all pattern in match expressions.
+ */
 class WildcardLiteral extends Expr {
   SourceLocation loc;
 
@@ -720,6 +738,9 @@ public int hashCode() {
   }
 }
 
+/**
+ * A boolean literal ({@code true} or {@code false}).
+ */
 class BoolLiteral extends Expr {
   boolean value;
   SourceLocation loc;
@@ -773,6 +794,10 @@ public int hashCode() {
   }
 }
 
+/**
+ * A string literal delimited by double quotes.
+ * Like {@code "apfelstrudel"}
+ */
 class StringLiteral extends Expr {
   String token;
   String value;
@@ -1293,6 +1318,10 @@ public int hashCode() {
   }
 }
 
+/**
+ * A range expression of the form {@code from..to}.
+ * Used in forall expression/statements, slicing, and sequence literals.
+ */
 class RangeExpr extends Expr {
   @Child
   Expr from;
@@ -1511,6 +1540,12 @@ default IsId path() {
   Node target();
 }
 
+/**
+ * An identifier path pointing to one or multiple nested namespaces, separated by {@code ::}.
+ * The first N-1 segments are namespace references and the last segment is the actual identifier.
+ *
+ * <p>Example: {@code MyIsa::MyFormat::fieldName}
+ */
 final class IdentifierPath extends Expr implements IsId {
   /**
    * List of segments in this path; the first N-1 segments are (nested) namespaces,
@@ -1993,6 +2028,11 @@ public SourceLocation location() {
   }
 }
 
+/**
+ * A conditional expression of the form {@code if condition then thenExpr else elseExpr}.
+ * Unlike {@link IfStatement}, the expression form always requires an else branch
+ * since it must evaluate to a value.
+ */
 class IfExpr extends Expr {
   @Child
   Expr condition;
@@ -2066,6 +2106,12 @@ public int hashCode() {
   }
 }
 
+/**
+ * A let expression that binds a value to one or more identifiers within a body expression.
+ * Written as {@code let x = expr in body}.
+ * Supports tuple unpacking when multiple identifiers are provided:
+ * {@code let a, b = tupleExpr in body}.
+ */
 class LetExpr extends Expr {
   List<Identifier> identifiers;
   @Child
@@ -2170,6 +2216,12 @@ public int hashCode() {
   }
 }
 
+/**
+ * A type cast expression using the {@code as} keyword.
+ * Performs explicit type conversions between VADL types, e.g. for signed/unsigned arithmetic.
+ *
+ * <p>Example: {@code value as UInt<32>}
+ */
 class CastExpr extends Expr {
   @Child
   Expr value;
@@ -2241,6 +2293,12 @@ public int hashCode() {
   }
 }
 
+/**
+ * A match expression that selects a result based on pattern matching.
+ * Written as {@code match expr with { pattern => result, ..., _ => default }}.
+ * Each case has one or more patterns on the LHS and a result expression on the RHS of {@code =>}.
+ * Must contain a wildcard {@code _} as the default catch-all case.
+ */
 class MatchExpr extends Expr {
   Expr candidate;
   List<Case> cases;
@@ -2369,6 +2427,11 @@ public int hashCode() {
   }
 }
 
+/**
+ * An existential quantifier expression over a set of operations.
+ * Written as {@code exists in {op1, op2, ...}}.
+ * Evaluates to true if the current context matches any of the listed operations.
+ */
 class ExistsInExpr extends Expr {
   List<IsId> operations;
   SourceLocation loc;
@@ -2425,6 +2488,11 @@ public int hashCode() {
   }
 }
 
+/**
+ * An existential quantifier expression with a body.
+ * Written as {@code exists x in {op1, op2, ...} then expr}.
+ * Binds identifiers to operations from the given set and evaluates the body expression.
+ */
 class ExistsInThenExpr extends Expr {
   List<Condition> conditions;
   @Child
@@ -2625,6 +2693,12 @@ enum Operation {
   }
 }
 
+/**
+ * A reference literal that references a structural element using the {@code @} prefix.
+ * Written as {@code @identifier}, e.g. {@code @PC} to reference the program counter resource.
+ * This syntax is mostly used in the microarchitecture to differentiate between direct usages and
+ * references.
+ */
 class ResourceReferenceExression extends Expr {
   @Child
   Identifier resource;
@@ -2672,6 +2746,12 @@ public int hashCode() {
   }
 }
 
+/**
+ * A sequence call expression used in the ABI modeling view to represent a list of alias
+ * registers with the same identifier.
+ * Provides syntactic sugar like {@code a{1..4}} which is equivalent to listing
+ * {@code a1, a2, a3, a4} individually.
+ */
 class SequenceCallExpr extends Expr {
 
   @Child

vadl/main/vadl/ast/Statement.java

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText : © 2025 TU Wien <vadl@tuwien.ac.at>
+// SPDX-FileCopyrightText : © 2025-2026 TU Wien <vadl@tuwien.ac.at>
 // SPDX-License-Identifier: GPL-3.0-or-later
 //
 // This program is free software: you can redistribute it and/or modify
@@ -66,6 +66,9 @@ interface StatementVisitor<T> {
   T visit(StatementList statement);
 }
 
+/**
+ * A block of multiple statements surrounded by curly braces.
+ */
 final class BlockStatement extends Statement {
   @Child
   List<Statement> statements;
@@ -216,6 +219,11 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * A conditional statement of the form {@code if condition then thenStmt else elseStmt}.
+ * Unlike {@link IfExpr}, the else branch is optional since a statement does not need
+ * to produce a value.
+ */
 final class IfStatement extends Statement {
   @Child
   Expr condition;
@@ -280,6 +288,10 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * An assignment statement that stores a value in a register, register file, or memory location.
+ * The target (LHS) and value expression (RHS) are separated by the {@code :=} operator.
+ */
 final class AssignmentStatement extends Statement {
   @Child
   Expr target;
@@ -333,6 +345,9 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * An ordered list of statements executed sequentially.
+ */
 final class StatementList extends Statement {
 
   @Child
@@ -365,6 +380,12 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * Marks the following statement as exceptional code.
+ * After the raise statement finishes, no further instruction behavior is executed.
+ *
+ * @see ExceptionDefinition
+ */
 final class RaiseStatement extends Statement {
 
   @Child
@@ -413,6 +434,10 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * A standalone call statement (e.g. a function or instruction call without assignment).
+ * Used for pseudo instruction definitions and ABI sequence definitions.
+ */
 final class CallStatement extends Statement {
 
   @Child
@@ -456,6 +481,10 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * An internal temporary placeholder node inside model definitions.
+ * This node should never leave the parser.
+ */
 final class PlaceholderStatement extends Statement {
 
   List<String> segments;
@@ -598,6 +627,12 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * A match statement that selects a statement to execute based on pattern matching.
+ * Written as {@code match expr with { pattern => stmt, ..., _ => default }}.
+ * Each case has one or more patterns on the LHS and a statement on the RHS of {@code =>}.
+ * The wildcard {@code _} default case is optional for statements (unlike {@link MatchExpr}).
+ */
 final class MatchStatement extends Statement {
   Expr candidate;
   List<Case> cases;
@@ -741,6 +776,11 @@ <R> R accept(StatementVisitor<R> visitor) {
   }
 }
 
+/**
+ * A call to an instruction or pseudo instruction.
+ * Supports both named arguments (using mapping syntax {@code {name = value}})
+ * and unnamed positional arguments.
+ */
 final class InstructionCallStatement extends Statement {
 
   @Child
@@ -885,6 +925,13 @@ public String toString() {
   }
 }
 
+/**
+ * A lock statement that gains exclusive access to a memory part,
+ * guaranteeing atomic read-modify-write operations.
+ * The lock is automatically released after the subsequent statement or block completes.
+ *
+ * <p>Written as {@code lock expr in statement}.
+ */
 final class LockStatement extends Statement {
   @Child
   Expr expr;
@@ -1006,6 +1053,11 @@ <R> R accept(StatementVisitor<R> visitor) {
 
 }
 
+/**
+ * An index variable binding in a {@link ForallStatement} or {@link ForallExpr}.
+ * Binds a name to a range domain.
+ * e.g. {@code i: Bits<8> in 0..3}.
+ */
 final class ForallIndex extends Node implements IdentifiableNode {
   @Child
   IsId name;