Refactor Part 3: Updating more Javadoc, changed LFSR initialization

README.md

@@ -22,8 +22,8 @@ These controls may change, and I may add a controls config in the future.
 ___
 
 ## TODO
-- Update hitboxes for bricks (the plan is to have individual sections of the brick make the ball move differently upon impact, sorta like how I did it in [the QuickBASIC version of the game](https://codeberg.org/boyfailure/quickout/src/branch/main/QUICKOUT.BAS))
-- Add complete javadoc
-- Implement menus
+- Add complete Javadoc (WIP 2025-05-18)
+- Implement menus (WIP 2025-05-18)
 - Look into sound effects
-- Clean up/optimize rendering code
+- Clean up/optimize rendering code
+- ~~Update hitboxes for bricks (the plan is to have individual sections of the brick make the ball move differently upon impact, sorta like how I did it in [the QuickBASIC version of the game](https://codeberg.org/boyfailure/quickout/src/branch/main/QUICKOUT.BAS))~~ Completed 2025-05-18

src/main/java/dev/boyfailure/vectorbreakout/LFSR.java

@@ -21,46 +21,78 @@ import java.awt.event.ActionListener;
 import javax.swing.Timer;
 
 /**
- * A software implementation of a LFSR-based (linear frequency shift register) pseudo-random number generator.
+ * A software implementation of a LFSR-based (linear frequency shift register)
+ * pseudo-random number generator.
+ *
  * @author Naomi (boyfailure.dev)
  * @since 1.0
  */
 public class LFSR {
 
-    private static boolean[] originalArray = new boolean[] {true,false,true,true,true,true,true,true,false,true,false,false,false,true,true,false,false};
-
     private boolean[] bitArray;
     private int bitCount;
     private int bitsReturned;
     private int firstXorIndex;
     private int secondXorIndex;
 
+    /**
+     * The timer to loop number generation.
+     * @since 1.0
+     */
     private Timer lfsrTimer;
 
+    /**
+     * Constructs a new LFSR of a configurable size.
+     * @param bitCount The number of bits in the register
+     * @param bitsReturned The size of the readable output, in bits
+     * @param firstXorIndex The index of the first bit in the XOR function
+     * @param secondXorIndex The index of the second bit in the XOR function
+     * @since 1.0
+     */
     public LFSR(int bitCount, int bitsReturned, int firstXorIndex, int secondXorIndex) {
         this.bitCount = bitCount;
         this.bitsReturned = bitsReturned;
         this.firstXorIndex = firstXorIndex;
         this.secondXorIndex = secondXorIndex;
+
+        // If the output bit amount is larger than the whole register, make them match to prevent overflows
         if (bitsReturned > bitCount) {bitsReturned = bitCount;}
+
+        // Initialize the bits and set them all to 1
         bitArray = new boolean[bitCount];
         for (int i = 0; i < bitCount; i++) {
-            if (i < 17) {bitArray[i] = LFSR.originalArray[i];}
-            else {
-                bitArray[i] = bitArray[i - 3] ^ bitArray[i - 8];
-            }
+            bitArray[i] = true;
         }
+
+        // Initialize and start the RNG loop.
         this.lfsrTimer = new Timer(1, new ActionListener(){public void actionPerformed(ActionEvent e) {LFSR.this.shift();}});
         this.lfsrTimer.start();
     }
+
+    /**
+     * Constructs a new LFSR of the default size.
+     * The default configuration is a 17-bit register that returns an 8-bit
+     * integer value from 0 to 255. The 12th and 17th bit are used for the XOR
+     * function.
+     * @since 1.0
+     */
     public LFSR() {
         this(17, 8, 11, 16);
     }
 
+    /**
+     * Returns the base-10 representation of the output bits as an integer.
+     * @return the base-10 representation of the output bits
+     * @since 1.0
+     */
     public int getDecimalValue() {
         int regValue = 0;
         int bitIndex = this.bitCount - 1;
 
+        /*
+         * Iterate through the bits from least-significant to most-significant
+         * and use powers of 2 to get the base-10 value
+         */
         for (int i = 0; i < this.bitsReturned; i++) {
             if (this.bitArray[bitIndex]) {
                 regValue += Math.pow(2, i);
@@ -70,11 +102,23 @@ public class LFSR {
 
         return regValue;
     }
+    /**
+     * Performs the bit-shift operation and then returns the resulting base-10
+     * representation of the output bits as an integer.
+     * @return the base-10 representation of the output bits
+     * @since 1.0
+     */
     public int getShiftedDecimalValue() {
         this.shift();
         return this.getDecimalValue();
     }
 
+    /**
+     * Shifts the bits towards the least-significant side and adds a new
+     * most-significant bit by performing the XOR operation with the
+     * firstXorIndex and secondXorIndex.
+     * @since 1.0
+     */
     public void shift() {
         for (int i = (this.bitCount - 1); i > 0; i--) {
             this.bitArray[i] = this.bitArray[i - 1];
@@ -82,6 +126,10 @@ public class LFSR {
         this.bitArray[0] = this.bitArray[this.firstXorIndex] ^ this.bitArray[this.secondXorIndex];
     }
 
+    /**
+     * Returns a String representation of the output bits' binary value.
+     * @return the output bits' binary value as a String
+     */
     public String getBits() {
         String result = "";
         for (int i = 0; i < this.bitCount; i++) {

src/main/java/dev/boyfailure/vectorbreakout/MenuItem.java

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2025 naomi.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package dev.boyfailure.vectorbreakout;
+
+/**
+ *
+ * @author naomi
+ */
+public class MenuItem {
+    
+}

src/main/java/dev/boyfailure/vectorbreakout/TextElement.java

@@ -42,7 +42,7 @@ public class TextElement {
     private GameState gameState;
 
     /**
-     * Text elements.
+     * Constructs a text object to be displayed on screen.
      * @param gameState the GameState in which the TextElement will reside
      * @param text the text that will be displayed
      * @param textScale the size of the text on screen
@@ -62,7 +62,7 @@ public class TextElement {
     }
     
     /**
-     * Text elements with a fadeout timer
+     * Constructs a text object that disappears after a set amount of time.
      * @param gameState the GameState in which the TextElement will reside
      * @param text the text that will be displayed
      * @param textScale the size of the text on screen

src/main/java/dev/boyfailure/vectorbreakout/package-info.java

@@ -0,0 +1,10 @@
+/**
+ * A clone of the classic arcade game Breakout with a vector graphics artstyle
+ * inspired by Atari QuadraScan games of the late 1970s-early 1980s,
+ * particularly Tempest.
+ *
+ * @since 20250323
+ * @author Naomi (boyfailure.dev)
+ * @version 1.0
+ */
+package dev.boyfailure.vectorbreakout;