Add docs, error handling for my rushed work from 2 years ago

Author: ausbin

src/main/java/io/zucchini/circuitsimtester/api/BaseMemory.java

@@ -3,9 +3,15 @@
 import java.io.InputStream;
 import java.util.Scanner;
 
+/**
+ * Base class inherited by {@link Ram} and {@link Rom}. Handles loading {@code
+ * .dat}s exported from CircuitSim from an {@link InputStream}.
+ */
 public abstract class BaseMemory {
     public abstract void store(int address, int value);
 
+    // TODO: Provide some mechanism in CircuitSimExtension to open a file
+    //       and preload it into RAM/ROM
     /**
      * Loads a stream of a dat file into this component's memory. Format
      * is the same as the .dat files saved in the CircuitSim memory

src/main/java/io/zucchini/circuitsimtester/api/Button.java

@@ -1,11 +1,19 @@
 package io.zucchini.circuitsimtester.api;
 
-// TODO FIXME document
+/**
+ * Allows pretending to push a button placed in a subcircuit.
+ * <p>
+ * (In reality, this manipulates an InputPin wired to where the button was;
+ * see {@link MockPulser})
+ */
 public class Button extends MockPulser {
     public Button(InputPin mockPin, Subcircuit subcircuit) {
         super(mockPin, subcircuit);
     }
 
+    /**
+     * This pushes the button. Crazy, right?
+     */
     public void press() {
         pulse();
     }

src/main/java/io/zucchini/circuitsimtester/api/Clock.java

@@ -2,16 +2,35 @@
 
 import java.util.function.BooleanSupplier;
 
-// TODO FIXME document
+/**
+ * Allows pretending to tick a Clock component placed in a subcircuit.
+ * <p>
+ * (In reality, this manipulates an InputPin wired to where the clock component was;
+ * see {@link MockPulser})
+ */
 public class Clock extends MockPulser {
     public Clock(InputPin mockPin, Subcircuit subcircuit) {
         super(mockPin, subcircuit);
     }
 
+    /**
+     * Tick the clock once.
+     */
     public void tick() {
         pulse();
     }
 
+    /**
+     * Tick the clock until {@code stopWhen} returns true.
+     *
+     * @param maxCycleCount the number of cycles before timeout (to avoid
+     *                      infinitely spinning)
+     * @param stopWhen returns true when we can stop ticking the clock (e.g.,
+     *                 the student's processor has finished running and is
+     *                 sending the "done" signal)
+     * @return the number of ticks performed until stopWhen returned true. May
+     *         be zero if the condition was initially met
+     */
     public long tickUntil(long maxCycleCount, BooleanSupplier stopWhen) {
         long ticks = 0;
         while (!stopWhen.getAsBoolean()) {

src/main/java/io/zucchini/circuitsimtester/api/MockPulser.java

@@ -1,6 +1,24 @@
 package io.zucchini.circuitsimtester.api;
 
-// TODO FIXME document
+/**
+ * Similar to {@link MockRegister} but much simpler: manipulates an InputPin
+ * which replaced a clock or button and is used to send "pulses" into the
+ * circuit. By "pulse", I mean an input like this:
+ * <pre>
+ * 1            _
+ *             | |
+ *             | |
+ *             | |
+ * 0 __________| |___________
+ *
+ *         Time ---&gt;
+ * </pre>
+ * Notice that could be a button press or the rising edge of the clock signal
+ * (in CircuitSim we do not have to worry about propagation delay, thank God),
+ * hence this is a base class used for {@link Button} and {@link Clock}. Those
+ * classes have their own more specialized methods for sending pulses that
+ * ultimately call {@link #pulse()}.
+ */
 public abstract class MockPulser {
     protected InputPin mockPin;
     protected Subcircuit subcircuit;
@@ -18,6 +36,10 @@ public Subcircuit getSubcircuit() {
         return subcircuit;
     }
 
+    /**
+     * Set the mock pin to 0, then 1, then 0 again to simulate the "pulse"
+     * drawn above in the lede.
+     */
     protected void pulse() {
         mockPin.set(0b0);
         mockPin.set(0b1);

src/main/java/io/zucchini/circuitsimtester/api/Register.java

@@ -60,7 +60,25 @@ public com.ra4king.circuitsim.simulator.components.memory.Register getRegister()
         return reg;
     }
 
-    // TODO FIXME document
+    /**
+     * Mocks this register with a {@link MockRegister}. See {@link
+     * MockRegister} and {@link
+     * Subcircuit#mockRegister(com.ra4king.circuitsim.simulator.components.memory.Register)}
+     * for details.
+     * <p>
+     * You probably <b>should not be calling this directly</b> — use the
+     * following code instead and let {@link
+     * io.zucchini.circuitsimtester.extension.CircuitSimExtension} handle this
+     * for you:
+     * <pre>
+     * {@literal @}SubcircuitComponent(bits=16)
+     * private MockRegister myFunRegister;
+     * </pre>
+     *
+     * @return a mocked version of this register
+     * @see MockRegister
+     * @see Subcircuit#mockRegister(com.ra4king.circuitsim.simulator.components.memory.Register)
+     */
     public MockRegister mock() {
         return subcircuit.mockRegister(reg);
     }

src/main/java/io/zucchini/circuitsimtester/api/Rom.java

@@ -3,7 +3,7 @@
 import com.ra4king.circuitsim.simulator.components.memory.ROM;
 
 /**
- * Wraps a CircuitSim RAM component.
+ * Wraps a CircuitSim ROM component.
  *
  * @author Austin Adams
  */
@@ -12,10 +12,10 @@ public class Rom extends BaseMemory {
     private Subcircuit subcircuit;
 
     /**
-     * Creates a new Ram which wraps the provided {@code RAM}
+     * Creates a new Rom which wraps the provided {@code ROM}
      * component and which lives in the provided {@code Subcircuit}.
      *
-     * @param rom {@code RAM} component to wrap
+     * @param rom {@code ROM} component to wrap
      * @param subcircuit where this pin lives
      */
     public Rom(ROM rom, Subcircuit subcircuit) {
@@ -30,13 +30,13 @@ public void store(int address, int value) {
     }
 
     /**
-     * Returns the internal CircuitSim {@code RAM} component this
+     * Returns the internal CircuitSim {@code ROM} component this
      * object wraps.
      * <p>
      * <b>This exposes an internal CircuitSim API. Do not use unless you
      *    know what you are doing.</b>
      *
-     * @return the CircuitSim {@code RAM} component wrapped by this
+     * @return the CircuitSim {@code ROM} component wrapped by this
      *         object.
      */
     public ROM getROM() {