address some MR comments and add doc

Author: Killian Perlin

lkql/lkql.lkt

@@ -1229,7 +1229,7 @@ class ClassField : LkqlNode {
 }
 
 |" Special annotation to specify the entry point for the nanopass framework.
-|" The pass designated by the associate identifier and all its transitive
+|" The pass designated by the associated identifier and all its transitive
 |" dependencies are going to be executed.
 class RunPass: LkqlNode {
     @parse_field

lkql_jit/language/src/main/java/com/adacore/lkql_jit/langkit_translator/passes/Hierarchy.java

@@ -69,12 +69,16 @@ public class Hierarchy {
     private boolean[] inheritanceMatrix;
     private HashMap<String, Integer> classNamesToIndex;
 
+    /** Setter for all the fields of the class. */
     private void become(int size, boolean[] matrix, HashMap<String, Integer> index) {
         this.classCount = size;
         this.inheritanceMatrix = matrix;
         this.classNamesToIndex = index;
     }
 
+    /**
+     * Computes a hierarchy of currently available classes in the Lkt bindings.
+     */
     @TruffleBoundary
     public static Hierarchy initial() {
         // Collect all inital classes
@@ -125,11 +129,17 @@ public boolean isInstance(String classX, String classY) {
             classNamesToIndex.get(classY)];
     }
 
+    /**
+     * Add a new class to the hierarchy, with no superclass nor subclass.
+     */
     @TruffleBoundary
     public void add(String classX) {
         addAll(Collections.singleton(classX));
     }
 
+    /**
+     * Add new classes to the hierarchy, with no superclasses nor subclasses.
+     */
     @TruffleBoundary
     public void addAll(Collection<String> classes) {
         final int size = this.size() + classes.size();
@@ -176,11 +186,17 @@ public void addInstanceOfRelation(String classX, String classY) {
         }
     }
 
+    /**
+     * Remove a class and all its subclasses from the hierarchy.
+     */
     @TruffleBoundary
     public void remove(String classX) {
         removeAll(Collections.singleton(classX));
     }
 
+    /**
+     * Remove all classes and all their subclasses from the hierarchy.
+     */
     @TruffleBoundary
     public void removeAll(Collection<String> classes) {
         // Compute all the subtypes of X to mask wich row/column to keep
@@ -236,6 +252,7 @@ public void removeAll(Collection<String> classes) {
     }
 
     // Primarily used in testing
+    /** Equality implementation */
     @TruffleBoundary
     public boolean equals(Object otherObject) {
         if (otherObject == null) return false;

lkql_jit/language/src/main/java/com/adacore/lkql_jit/langkit_translator/passes/PassContext.java

@@ -21,7 +21,7 @@
  */
 public class PassContext {
 
-    /** maps a class name to its available members */
+    /** This is a map from class names to all its available members. */
     public final HashMap<String, ClassDescriptor> env;
 
     private PassContext() {

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/expressions/DynamicConstructorCall.java

@@ -18,7 +18,6 @@
  * {@link ConstructorCall}. The type of node is decided in the lowering
  * pass, thanks to a flag set when entering a pass node.
  */
-
 public final class DynamicConstructorCall extends Expr {
 
     // ----- Children -----
@@ -39,8 +38,10 @@ public DynamicConstructorCall(SourceSection location, String nodeKind, ArgList a
         this.nodeKind = nodeKind;
         this.args = argList;
         for (var arg : argList.getArgs()) {
-            if (arg instanceof NamedArg) continue;
-            throw LKQLRuntimeException.fromMessage("constructors in passes only accept named args");
+            if (!(arg instanceof NamedArg)) throw LKQLRuntimeException.fromMessage(
+                "constructors in passes only accept named args",
+                arg
+            );
         }
     }
 

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/expressions/FunExpr.java

@@ -27,7 +27,13 @@ public final class FunExpr extends Expr {
     /** Closure descriptor of the function. */
     private final ClosureDescriptor closureDescriptor;
 
-    /** The root node representing the function execution. */
+    /**
+     * The root node representing the function execution.
+     *
+     * This field doesn't need to be a child for execution purposes,
+     * but this is temporarilly needed until the {@link ResolutionPass}
+     * is removed and the nanopass framework rellies on static typing only.
+     */
     @Child
     private FunctionRootNode functionRootNode;
 

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/pass/AddBlock.java

@@ -34,7 +34,10 @@ public Object executeGeneric(VirtualFrame frame) {
 
     @Override
     public String toString(int indentLevel) {
-        // TODO Auto-generated method stub
-        throw new UnsupportedOperationException("Unimplemented method 'toString'");
+        return nodeRepresentation(
+            indentLevel,
+            new String[] { "classes", "fields" },
+            new Object[] { classes, fields }
+        );
     }
 }

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/pass/ClassDecl.java

@@ -34,7 +34,10 @@ public Object executeGeneric(VirtualFrame frame) {
 
     @Override
     public String toString(int indentLevel) {
-        // TODO Auto-generated method stub
-        throw new UnsupportedOperationException("Unimplemented method 'toString'");
+        return nodeRepresentation(
+            indentLevel,
+            new String[] { "name", "fields" },
+            new Object[] { name, fields }
+        );
     }
 }

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/pass/DelBlock.java

@@ -34,7 +34,10 @@ public Object executeGeneric(VirtualFrame frame) {
 
     @Override
     public String toString(int indentLevel) {
-        // TODO Auto-generated method stub
-        throw new UnsupportedOperationException("Unimplemented method 'toString'");
+        return nodeRepresentation(
+            indentLevel,
+            new String[] { "classes", "fields" },
+            new Object[] { classes, fields }
+        );
     }
 }

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/pass/PassExpr.java

@@ -28,17 +28,23 @@
 @NodeChild(value = "readInput", type = ReadArgument.class)
 public abstract class PassExpr extends Expr {
 
+    // This field doesn't need to be a child with regard to execution,
+    // and so its contents could be merged into this class.
     @Child
     private AddBlock add;
 
+    // This field doesn't need to be a child with regard to execution,
+    // and so its contents could be merged into this class.
     @Child
     private DelBlock del;
 
+    // This field doesn't need to be a child with regard to execution,
+    // and so its contents could be merged into this class.
     @Child
     private RewriteBlock rewrite;
 
     /**
-     * the previous pass slot, None if this is the first pass in the chain
+     * The previous pass slot, (or `None` if this is the first pass in the chain).
      */
     private final Optional<Integer> previousSlot;
 
@@ -56,8 +62,6 @@ protected PassExpr(
         this.rewrite = rewrite;
     }
 
-    // TODO insert dynamic checks to verify AST integrity wrt. add / del blocks
-    // this can be removed if pattern matching exhaustivity is pre-checked
     @Specialization
     public Object onDynamicAdaNode(VirtualFrame frame, DynamicAdaNode input) {
         final var typingContext = LKQLLanguage.getContext(this).getTypingContext();
@@ -70,7 +74,7 @@ public Object onDynamicAdaNode(VirtualFrame frame, DynamicAdaNode input) {
     }
 
     @Fallback
-    public Object onOther(VirtualFrame frame, Object _obj1) {
+    public Object onOther(VirtualFrame frame, @SuppressWarnings("unused") Object obj) {
         throw LKQLRuntimeException.shouldNotExecute(this);
     }
 
@@ -103,7 +107,6 @@ public Optional<Integer> getPreviousSlot() {
 
     // core logic
 
-    // bottom up rewriting of the tree
     @TruffleBoundary
     private DynamicAdaNode getUpdatedTree(DynamicAdaNode tree, MaterializedFrame frame) {
         // recurse on children first (bottom up)

lkql_jit/language/src/main/java/com/adacore/lkql_jit/nodes/pass/PrefixField.java

@@ -12,8 +12,7 @@
 import com.oracle.truffle.api.source.SourceSection;
 
 /**
- * PrefixField
- * this is a POJO, it needs to be an LKQLNode
+ * This is a POJO, it needs to be an LKQLNode
  * to simplify lowering and the resolution pass
  * (see {@link ResolutionPass})
  */
@@ -35,7 +34,10 @@ public Object executeGeneric(VirtualFrame frame) {
 
     @Override
     public String toString(int indentLevel) {
-        // TODO Auto-generated method stub
-        throw new UnsupportedOperationException("Unimplemented method 'toString'");
+        return nodeRepresentation(
+            indentLevel,
+            new String[] { "prefix", "field" },
+            new Object[] { prefix, field }
+        );
     }
 }