Documentation and cleanup

Author: msimacek

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/BinaryOps.java

@@ -42,6 +42,7 @@
 
 import com.oracle.graal.python.annotations.GenerateEnumConstants;
 
+/** Operation identifiers for {@link OpCodes#BINARY_OP}. */
 @GenerateEnumConstants
 public enum BinaryOps {
     ADD,

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/Block.java

@@ -43,6 +43,9 @@
 import java.util.ArrayList;
 import java.util.EnumSet;
 
+/**
+ * Block of instructions. Not always exactly like basic block, we allow having jumps in the middle.
+ */
 final class Block {
     ArrayList<Instruction> instr = new ArrayList<>();
     Block next;

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/BlockInfo.java

@@ -42,6 +42,10 @@
 
 import com.oracle.graal.python.pegparser.sst.StmtTy;
 
+/**
+ * Linked stack of block-related information needed to unwind execution before {@code break},
+ * {@code continue} or {@code return}.
+ */
 class BlockInfo {
     BlockInfo outer;
 

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/CodeUnit.java

@@ -51,6 +51,11 @@
 import com.oracle.graal.python.compiler.OpCodes.CollectionBits;
 import com.oracle.graal.python.util.PythonUtils;
 
+/**
+ * A context-independent representation of code for bytecode interpreter. Contains the actual
+ * bytecode and all the related data, like constants or exception handler ranges. It doesn't contain
+ * the filename to make it easier to keep in native images.
+ */
 public final class CodeUnit {
     public static final int HAS_DEFAULTS = 0x1;
     public static final int HAS_KWONLY_DEFAULTS = 0x2;

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/Compiler.java

@@ -144,6 +144,9 @@
 import com.oracle.graal.python.pegparser.sst.StmtTy;
 import com.oracle.graal.python.util.PythonUtils;
 
+/**
+ * Compiler for bytecode interpreter.
+ */
 public class Compiler implements SSTreeVisitor<Void> {
     public static final int BYTECODE_VERSION = 20;
 

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/compiler/FormatOptions.java

@@ -41,11 +41,32 @@
 package com.oracle.graal.python.compiler;
 
 public abstract class FormatOptions {
+    /**
+     * Mask to extract just the conversion type flags.
+     */
     public static final int FVC_MASK = 0x3;
+    /**
+     * No conversion (identity function).
+     */
     public static final int FVC_NONE = 0x0;
+    /**
+     * Conversion equivalent to builtin {@code str}
+     */
     public static final int FVC_STR = 0x1;
+    /**
+     * Conversion equivalent to builtin {@code repr}
+     */
     public static final int FVC_REPR = 0x2;
+    /**
+     * Conversion equivalent to builtin {@code ascii}
+     */
     public static final int FVC_ASCII = 0x3;
+    /**
+     * Mask to extract just the spec flag.
+     */
     public static final int FVS_MASK = 0x4;
+    /**
+     * Whether a format spec is present.
+     */
     public static final int FVS_HAVE_SPEC = 0x4;
 }