Merge pull request #7 from PRL-PRG/documentation

Documentation, add simple scalar scalar SEXPs, weak warnings, cleanup

.gitignore

@@ -1,4 +1,4 @@
-.snapshots/**/*.fail*
+**/src/test/snapshots/**/*.fail*
 
 ### Build ###
 target/

pom.xml

@@ -59,16 +59,8 @@
     </dependency>
   </dependencies>
   <build>
-    <testResources>
-      <!-- Resources including R scripts which are treated as data -->
-      <testResource>
-        <directory>src/test/resources</directory>
-      </testResource>
-      <!-- R scripts which are treated as code -->
-      <testResource>
-        <directory>src/test/R</directory>
-      </testResource>
-    </testResources>
+    <!-- Snapshots aren't test resources, because we have to write to them, so we access them
+         at their actual locations (bundled are overridden on recompile). -->
     <plugins>
       <!-- git-build-hook, install git hooks when you run any maven command so you don't forget -->
       <plugin>

src/main/java/Main.java

@@ -1,27 +1,36 @@
 import java.io.FileInputStream;
 import java.io.IOException;
 import java.io.InputStream;
+import org.prlprg.rds.RDSException;
 import org.prlprg.rds.RDSReader;
 import org.prlprg.sexp.SEXP;
 import org.prlprg.util.IO;
 
+/**
+ * TODO right now reads a command-line argument pointing to an RDS file containing an AST closure,
+ * reads that closure, compiles it, and debug-prints the output. In the future, this will start the
+ * compile server, and command-line arguments will probably be a list of ports it will bind to (and
+ * possibly flags for other modes, "-h" and "-v").
+ */
 public class Main {
-
-  public static void main(String[] args) throws Exception {
+  /**
+   * @see Main
+   */
+  public static void main(String[] args) throws IOException, RDSException {
     new Main().doMain(args);
   }
 
-  private void doMain(String[] args) throws Exception {
+  private void doMain(String[] args) throws IOException, RDSException {
     compile(args[0]);
   }
 
-  private void compile(String file) throws IOException {
+  private void compile(String file) throws IOException, RDSException {
     try (var input = new FileInputStream(file)) {
       compile(input);
     }
   }
 
-  private void compile(InputStream input) throws IOException {
+  private void compile(InputStream input) throws IOException, RDSException {
     compile(RDSReader.readStream(IO.maybeDecompress(input)));
   }
 

src/main/java/org/prlprg/App.java

@@ -2,6 +2,7 @@
 
 /** Hello world! */
 public class App {
+  @SuppressWarnings("MissingJavadoc")
   public static void main(String[] args) {
     System.out.println("Hello World!");
   }

src/main/java/org/prlprg/RVersion.java

@@ -12,6 +12,11 @@ public record RVersion(int major, int minor, int patch, @Nullable String suffix)
   /** The latest version we handle. */
   public static final RVersion LATEST_AWARE = new RVersion(4, 3, 2);
 
+  /**
+   * Parse a version number from a string.
+   *
+   * @throws IllegalArgumentException if the string is not a valid version number.
+   */
   public static RVersion parse(String textual) {
     var parts = textual.split("\\.");
 

src/main/java/org/prlprg/bc/BcCode.java

@@ -103,7 +103,7 @@ public String toString() {
    * <p>Not synchronized, so don't use from multiple threads.
    */
   public static class Builder {
-    ImmutableList.Builder<BcInstr> builder = ImmutableList.builder();
+    final ImmutableList.Builder<BcInstr> builder = ImmutableList.builder();
 
     /** Create a new builder. */
     public Builder() {}

src/main/java/org/prlprg/bc/BcFromRawException.java

@@ -1,11 +1,15 @@
 package org.prlprg.bc;
 
+/**
+ * Exception thrown when a raw byte-array and constant list can't be converted to typed bytecode
+ * ({@link Bc}).
+ */
 public class BcFromRawException extends RuntimeException {
-  public BcFromRawException(String message) {
+  BcFromRawException(String message) {
     super(message);
   }
 
-  public BcFromRawException(String message, Throwable cause) {
+  BcFromRawException(String message, Throwable cause) {
     super(message, cause);
   }
 }

src/main/java/org/prlprg/bc/BcInstr.java

@@ -11,6 +11,7 @@
  * A single bytecode instruction, consists of an operation and arguments. The operation is
  * determined by its subtype, arguments are determined by its fields.
  */
+@SuppressWarnings("MissingJavadoc")
 @Immutable
 public sealed interface BcInstr {
   /** The instruction's operation. */
@@ -300,15 +301,15 @@ public BcOp op() {
   }
 
   record MakeClosure(ConstPool.TypedIdx<VecSXP> formalsBodyAndMaybeSrcRef) implements BcInstr {
-    ListSXP formals(ConstPool pool) {
+    public ListSXP formals(ConstPool pool) {
       return (ListSXP) pool.get(this.formalsBodyAndMaybeSrcRef).get(0);
     }
 
-    SEXP body(ConstPool pool) {
+    public SEXP body(ConstPool pool) {
       return pool.get(formalsBodyAndMaybeSrcRef).get(1);
     }
 
-    SEXP srcRef(ConstPool pool) {
+    public SEXP srcRef(ConstPool pool) {
       var formalsBodyAndMaybeSrcRef = pool.get(this.formalsBodyAndMaybeSrcRef);
       return formalsBodyAndMaybeSrcRef.size() < 3 ? SEXPs.NULL : formalsBodyAndMaybeSrcRef.get(2);
     }

src/main/java/org/prlprg/bc/BcOp.java

@@ -1,6 +1,7 @@
 package org.prlprg.bc;
 
 /** Bytecode operations. Synced with those in `gnur/src/eval.c`. */
+@SuppressWarnings({"MissingJavadoc", "SpellCheckingInspection"})
 public enum BcOp {
   BCMISMATCH,
   RETURN,

src/main/java/org/prlprg/bc/ConstPool.java

@@ -106,7 +106,7 @@ public Idx next() {
   }
 
   /**
-   * Create from the raw GNU-R representation.
+   * Create from a constant list (raw GNU-R representation).
    *
    * @return The pool and a function to create pool indices from raw integers, since that isn't
    *     ordinarily exposed.
@@ -179,6 +179,10 @@ public String toString() {
     }
   }
 
+  /**
+   * A {@link Idx} (typed index into a bytecode pool) which further checks that the {@link SEXP} is
+   * of a specific type.
+   */
   @SuppressFBWarnings(
       value = "EQ_DOESNT_OVERRIDE_EQUALS",
       justification =
@@ -306,6 +310,7 @@ private <S extends SEXP> TypedIdx<S> of(int i, Class<S> sexpInterface) {
     }
   }
 
+  /** Caused by trying to subscript one bytecode pool with an index from another. */
   public static class WrongPoolException extends RuntimeException {
     private WrongPoolException() {
       super("Wrong pool");

src/main/java/org/prlprg/bc/package-info.java

@@ -1,4 +1,4 @@
-/** GNU-R bytecode representation. */
+/** GNU-R typed bytecode representation. */
 @ParametersAreNonnullByDefault
 @FieldsAreNonNullByDefault
 @ReturnTypesAreNonNullByDefault

src/main/java/org/prlprg/compile/Compiler.java

@@ -7,11 +7,17 @@
 import org.prlprg.bc.BcInstr;
 import org.prlprg.sexp.*;
 
+/**
+ * The GNU-R bytecode compiler reimplemented in Java.
+ *
+ * <p>This is <b>not</b> the PIR or native code compiler.
+ */
 public class Compiler {
   private static final Set<String> MAYBE_NSE_SYMBOLS = Set.of("bquote");
 
   private final Bc.Builder cb = new Bc.Builder();
 
+  /** Compile a function. */
   public static Bc compileFun(CloSXP source) {
     var body = source.body();
 
@@ -20,6 +26,7 @@ public static Bc compileFun(CloSXP source) {
     return compile(body, SEXPs.EMPTY_ENV);
   }
 
+  /** TODO what does this method do? */
   public static Bc compile(SEXP expr, EnvSXP env) {
     // TODO: add local variables into the context environment?
     return compile(expr, new Context(true, true, env));

src/main/java/org/prlprg/compile/CompilerException.java

@@ -1,7 +1,8 @@
 package org.prlprg.compile;
 
+/** Exception thrown from {@link Compiler}. */
 public class CompilerException extends RuntimeException {
-  public CompilerException(String message) {
+  CompilerException(String message) {
     super(message);
   }
 }

src/main/java/org/prlprg/compile/package-info.java

@@ -1,4 +1,4 @@
-/** Compile GNU-R ASTs (S-expressions) into bytecode. */
+/** Compile SEXP ASTs into bytecode. */
 @ParametersAreNonnullByDefault
 @FieldsAreNonNullByDefault
 @ReturnTypesAreNonNullByDefault

src/main/java/org/prlprg/package-info.java

@@ -1,3 +1,4 @@
+/** R compiler server */
 @ParametersAreNonnullByDefault
 @FieldsAreNonNullByDefault
 @ReturnTypesAreNonNullByDefault

src/main/java/org/prlprg/primitive/Constants.java

@@ -1,18 +1,35 @@
 package org.prlprg.primitive;
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import org.prlprg.sexp.SEXPs;
 
+/** Constants for R runtime primitives. Other constants are in {@link SEXPs}. */
 @SuppressFBWarnings(
     value = {"DM_STRING_CTOR", "ES_COMPARING_PARAMETER_STRING_WITH_EQ"},
     justification = "NA_STRING has to be a unique string, and we compare via direct equality")
 public final class Constants {
   // according to Arith.h
+  /**
+   * Minimum value representable in an R integer, since {@link Integer#MIN_VALUE} is used for NA.
+   */
+  public static final int INT_MIN = Integer.MIN_VALUE + 1;
+
+  /** The actual value of an {@code NA} element of an integer vector in GNU-R. */
   public static final int NA_INT = Integer.MIN_VALUE;
+
+  /** The actual value of an {@code NA} element of a real vector in GNU-R. */
   public static final double NA_REAL = Double.NaN;
 
+  /**
+   * The "NA string": a unique string that is compared for identity which represents NA values.
+   *
+   * <p>Note: This is <b>not</b> encoded the same as GNU-R's NA string (because they're both
+   * pointers), so it must be handled in serialization and deserialization.
+   */
   @SuppressWarnings("StringOperationCanBeSimplified")
   public static final String NA_STRING = new String("!!!NA_STRING!!!");
 
+  /** Check if a string is the NA string. */
   @SuppressWarnings("StringEquality")
   public static boolean isNaString(String s) {
     return s == NA_STRING;

src/main/java/org/prlprg/primitive/Logical.java

@@ -1,9 +1,12 @@
 package org.prlprg.primitive;
 
-/** GNU-R "logical": a boolean which also permits NA (trinary). */
+/** R "logical": a boolean which also permits NA (trinary). */
 public enum Logical {
+  @SuppressWarnings("MissingJavadoc")
   FALSE(0),
+  @SuppressWarnings("MissingJavadoc")
   TRUE(1),
+  @SuppressWarnings("MissingJavadoc")
   NA(Integer.MIN_VALUE);
 
   /** The value in GNU-R */

src/main/java/org/prlprg/primitive/Names.java

@@ -4,6 +4,7 @@
 
 /** Special symbols */
 public final class Names {
+  /** The symbols which are treated as binary-operators in R (when parsing or printing). */
   public static final ImmutableList<String> BINOPS =
       ImmutableList.of(
           "+", "-", "*", "/", "^", "%%", "%/%", "==", "!=", "<", "<=", ">", ">=", "&", "|", "&&",

src/main/java/org/prlprg/primitive/package-info.java

@@ -1,4 +1,4 @@
-/** GNU-R simple struct datatypes and values which aren't s-exoressions or contexts. */
+/** Simple struct datatypes and values in R which aren't SEXPs or contexts. */
 @ParametersAreNonnullByDefault
 @FieldsAreNonNullByDefault
 @ReturnTypesAreNonNullByDefault

src/main/java/org/prlprg/rds/RDSException.java

@@ -1,11 +1,12 @@
 package org.prlprg.rds;
 
-public class RDSException extends RuntimeException {
-  public RDSException(String message) {
+/** Thrown when deserializing R objects from malformed RDS. */
+public class RDSException extends Exception {
+  RDSException(String message) {
     super(message);
   }
 
-  public RDSException(String message, Throwable cause) {
+  RDSException(String message, Throwable cause) {
     super(message, cause);
   }
 }

src/main/java/org/prlprg/rds/RDSItemType.java

@@ -40,13 +40,15 @@ static RDSItemType valueOf(int i) {
     };
   }
 
+  /** SEXPType encoded as an RDS item type. */
   record Sexp(SEXPType sexp) implements RDSItemType {
     @Override
     public int i() {
       return sexp.i;
     }
   }
 
+  /** Special RDS item types. */
   enum Special implements RDSItemType {
     REFSXP(255),
     NILVALUE_SXP(254),