Fix Publish-Javadoc Action

.github/workflows/publish-javadoc.yml

@@ -10,7 +10,11 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
+
     steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
       - name: Publish JavaDoc
         uses: MathieuSoysal/Javadoc-publisher.yml@v2.4.0
         with:
@@ -19,4 +23,5 @@ jobs:
           java-version: 21
           java-distribution: temurin
           target-folder: docs
-          project: gradle
+          project: gradle
+          custom-command: ./gradlew javadoc -Pci

build.gradle

@@ -1,10 +1,14 @@
 plugins {
     id 'java'
-    id 'edu.sc.seis.launch4j' version '2.5.3'
+    id 'edu.sc.seis.launch4j' version '2.5.3' apply false
     id 'kr.motd.sphinx' version '2.10.0'
     id 'com.diffplug.spotless' version '6.25.0'
 }
 
+if (!project.hasProperty("ci")) {
+    apply plugin: 'edu.sc.seis.launch4j'
+}
+
 def versionFile = file('legup-update/src/main/resources/edu.rpi.legupupdate/VERSION')
 def appVersion = versionFile.exists() ? versionFile.text.trim() : 'VERSION_NOT_FOUND'
 version = appVersion

src/main/java/edu/rpi/legup/model/PuzzleImporter.java

@@ -9,6 +9,8 @@
 import java.util.*;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 import org.w3c.dom.Element;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
@@ -29,7 +31,7 @@ public abstract class PuzzleImporter {
      *
      * @param puzzle puzzle that is imported
      */
-    public PuzzleImporter(Puzzle puzzle) {
+    public PuzzleImporter(@NotNull Puzzle puzzle) {
         this.puzzle = puzzle;
     }
 
@@ -60,7 +62,7 @@ public void initializePuzzle(int rows, int columns) throws RuntimeException {
      * @throws IllegalArgumentException if the statements are not suitable for initializing the
      *     puzzle
      */
-    public void initializePuzzle(String[] statements)
+    public void initializePuzzle(@NotNull String[] statements)
             throws InputMismatchException, IllegalArgumentException {
         // Note: Error checking for the statements will be left up to the puzzles that support
         // text input. For example, some puzzles may be okay with "blank" statements (Strings with
@@ -74,7 +76,7 @@ public void initializePuzzle(String[] statements)
      * @param node the XML document node representing the puzzle
      * @throws InvalidFileFormatException if the file format is invalid
      */
-    public void initializePuzzle(Node node) throws InvalidFileFormatException {
+    public void initializePuzzle(@NotNull Node node) throws InvalidFileFormatException {
         if (node.getNodeName().equalsIgnoreCase("puzzle")) {
             org.w3c.dom.Element puzzleElement = (org.w3c.dom.Element) node;
 
@@ -143,7 +145,7 @@ public void initializePuzzle(Node node) throws InvalidFileFormatException {
      * @param node the XML document node representing the board
      * @throws InvalidFileFormatException if the file format is invalid
      */
-    public abstract void initializeBoard(Node node) throws InvalidFileFormatException;
+    public abstract void initializeBoard(@NotNull Node node) throws InvalidFileFormatException;
 
     /**
      * Initializes the board using an array of statements.
@@ -153,7 +155,7 @@ public void initializePuzzle(Node node) throws InvalidFileFormatException {
      * @throws IllegalArgumentException if the statements are not suitable for initializing the
      *     board
      */
-    public abstract void initializeBoard(String[] statements)
+    public abstract void initializeBoard(@NotNull String[] statements)
             throws UnsupportedOperationException, IllegalArgumentException;
 
     /**
@@ -164,6 +166,7 @@ public abstract void initializeBoard(String[] statements)
      * @return A list of elements that will change when solving the puzzle * e.g. {"cell"}, {"cell",
      *     "line"}
      */
+    @NotNull
     public List<String> getImporterElements() {
         List<String> elements = new ArrayList<>();
         elements.add("cell");
@@ -176,7 +179,7 @@ public List<String> getImporterElements() {
      * @param node xml document node
      * @throws InvalidFileFormatException if file is invalid
      */
-    public void initializeProof(Node node) throws InvalidFileFormatException {
+    public void initializeProof(@NotNull Node node) throws InvalidFileFormatException {
         if (node.getNodeName().equalsIgnoreCase("proof")) {
             org.w3c.dom.Element proofElement = (org.w3c.dom.Element) node;
             NodeList treeList = proofElement.getElementsByTagName("tree");
@@ -211,7 +214,7 @@ public void initializeProof(Node node) throws InvalidFileFormatException {
      * @param node xml document node
      * @throws InvalidFileFormatException if file is invalid
      */
-    protected void setCells(Node node) throws InvalidFileFormatException {
+    protected void setCells(@NotNull Node node) throws InvalidFileFormatException {
         NodeList dataList = ((org.w3c.dom.Element) node).getElementsByTagName("cell");
         Board board = puzzle.getCurrentBoard();
         for (int i = 0; i < dataList.getLength(); i++) {
@@ -227,7 +230,7 @@ protected void setCells(Node node) throws InvalidFileFormatException {
      * @param node xml document node
      * @throws InvalidFileFormatException if file is invalid
      */
-    protected void createTree(Node node) throws InvalidFileFormatException {
+    protected void createTree(@NotNull Node node) throws InvalidFileFormatException {
         Element treeElement = (org.w3c.dom.Element) node;
 
         Tree tree = new Tree();
@@ -320,8 +323,16 @@ protected void createTree(Node node) throws InvalidFileFormatException {
         }
     }
 
+    /**
+     * Validates the structure of the proof tree, checking for disjoint or cyclic elements.
+     *
+     * @param nodes the map of node IDs to TreeNode objects
+     * @param transitions the map of transition IDs to TreeTransition objects
+     * @throws InvalidFileFormatException if the tree structure is invalid
+     */
     protected void validateTreeStructure(
-            HashMap<String, TreeNode> nodes, HashMap<String, TreeTransition> transitions)
+            @NotNull HashMap<String, TreeNode> nodes,
+            @NotNull HashMap<String, TreeTransition> transitions)
             throws InvalidFileFormatException {
         Tree tree = puzzle.getTree();
 
@@ -402,7 +413,8 @@ protected void validateTreeStructure(
      * @throws InvalidFileFormatException if the XML node format is incorrect or unknown nodes are
      *     encountered
      */
-    protected void makeTransitionChanges(TreeTransition transition, Node transElement)
+    protected void makeTransitionChanges(
+            @NotNull TreeTransition transition, @NotNull Node transElement)
             throws InvalidFileFormatException {
         if (transition.getRule() instanceof MergeRule) {
             List<TreeNode> mergingNodes = transition.getParents();
@@ -462,7 +474,8 @@ protected void createDefaultTree() {
      *
      * @return puzzle
      */
+    @NotNull
     public Puzzle getPuzzle() {
         return puzzle;
     }
-}
+}

src/main/java/edu/rpi/legup/model/gameboard/ElementFactory.java

@@ -4,6 +4,7 @@
 import org.w3c.dom.Document;
 import org.w3c.dom.Element;
 import org.w3c.dom.Node;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * ElementFactory is an abstract class for importing and exporting {@link PuzzleElement} instances.
@@ -19,7 +20,7 @@ public abstract class ElementFactory {
      * @throws InvalidFileFormatException thrown if the xml node is invalid for the specific puzzle
      *     element
      */
-    public abstract PuzzleElement importCell(Node node, Board board)
+    public abstract @NotNull PuzzleElement importCell(@NotNull Node node, @NotNull Board board)
             throws InvalidFileFormatException;
 
     /**
@@ -29,5 +30,6 @@ public abstract PuzzleElement importCell(Node node, Board board)
      * @param puzzleElement PuzzleElement cell
      * @return xml PuzzleElement
      */
-    public abstract Element exportCell(Document document, PuzzleElement puzzleElement);
-}
+    public abstract @NotNull Element exportCell(
+            @NotNull Document document, @NotNull PuzzleElement puzzleElement);
+}

src/main/java/edu/rpi/legup/model/gameboard/GridBoard.java

@@ -5,6 +5,8 @@
 import edu.rpi.legup.puzzle.treetent.TreeTentClue;
 import java.awt.*;
 import java.awt.event.MouseEvent;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 /**
  * GridBoard represents a grid-based board where each cell can be manipulated based on its
@@ -45,6 +47,7 @@ public GridBoard(int size) {
      * @param y y location of the cell
      * @return grid cell at location (x, y)
      */
+    @Nullable
     public GridCell getCell(int x, int y) {
         if (y * dimension.width + x >= puzzleElements.size()
                 || x >= dimension.width
@@ -66,7 +69,7 @@ public GridCell getCell(int x, int y) {
      * @param y y location of the cell
      * @param cell grid cell to set at location (x,y)
      */
-    public void setCell(int x, int y, GridCell cell) {
+    public void setCell(int x, int y, @NotNull GridCell cell) {
         if (y * dimension.width + x >= puzzleElements.size()
                 || x >= dimension.width
                 || y >= dimension.height
@@ -77,7 +80,7 @@ public void setCell(int x, int y, GridCell cell) {
         puzzleElements.set(y * dimension.width + x, cell);
     }
 
-    public void setCell(int x, int y, Element e, MouseEvent m) {
+    public void setCell(int x, int y, @Nullable Element e, @NotNull MouseEvent m) {
         if (this instanceof TreeTentBoard
                 && ((y == dimension.height && 0 <= x && x < dimension.width)
                         || (x == dimension.width && 0 <= y && y < dimension.height))) {
@@ -153,6 +156,7 @@ public int getHeight() {
      *
      * @return the dimension of the grid board
      */
+    @NotNull
     public Dimension getDimension() {
         return dimension;
     }
@@ -162,6 +166,7 @@ public Dimension getDimension() {
      *
      * @return a new copy of the board that is independent of this one
      */
+    @NotNull
     public GridBoard copy() {
         GridBoard newGridBoard = new GridBoard(this.dimension.width, this.dimension.height);
         for (int x = 0; x < this.dimension.width; x++) {

src/main/java/edu/rpi/legup/puzzle/lightup/LightUp.java

@@ -7,6 +7,8 @@
 import edu.rpi.legup.model.rules.ContradictionRule;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 @RegisterPuzzle
 public class LightUp extends Puzzle {
@@ -37,7 +39,7 @@ public void initializeView() {
      * @return board of the random edu.rpi.legup.puzzle
      */
     @Override
-    public Board generatePuzzle(int difficulty) {
+    public @Nullable Board generatePuzzle(int difficulty) {
         return null;
     }
 
@@ -60,7 +62,7 @@ public boolean isValidDimensions(int rows, int columns) {
      * @return true if board is valid, false otherwise
      */
     @Override
-    public boolean isBoardComplete(Board board) {
+    public boolean isBoardComplete(@NotNull Board board) {
         LightUpBoard lightUpBoard = (LightUpBoard) board;
         lightUpBoard.fillWithLight();
 
@@ -75,7 +77,7 @@ public boolean isBoardComplete(Board board) {
         for (PuzzleElement data : lightUpBoard.getPuzzleElements()) {
             LightUpCell cell = (LightUpCell) data;
             if ((cell.getType() == LightUpCellType.UNKNOWN
-                            || cell.getType() == LightUpCellType.EMPTY)
+                    || cell.getType() == LightUpCellType.EMPTY)
                     && !cell.isLite()) {
                 return false;
             }
@@ -89,5 +91,5 @@ public boolean isBoardComplete(Board board) {
      * @param board the board that has changed
      */
     @Override
-    public void onBoardChange(Board board) {}
-}
+    public void onBoardChange(@NotNull Board board) {}
+}

src/main/java/edu/rpi/legup/puzzle/lightup/LightUpBoard.java

@@ -5,6 +5,8 @@
 import java.awt.*;
 import java.util.HashSet;
 import java.util.Set;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
 
 public class LightUpBoard extends GridBoard {
 
@@ -86,7 +88,7 @@ public void fillWithLight() {
      * @param cell LightUpCell
      * @return Set of adjacent LightUpCells
      */
-    public Set<LightUpCell> getAdj(LightUpCell cell) {
+    public @NotNull Set<LightUpCell> getAdj(@NotNull LightUpCell cell) {
         Set<LightUpCell> adjCells = new HashSet<>();
         cell = (LightUpCell) getPuzzleElement(cell);
 
@@ -117,7 +119,7 @@ public Set<LightUpCell> getAdj(LightUpCell cell) {
      * @param type specified type
      * @return the number of adjacent cells
      */
-    public int getNumAdj(LightUpCell cell, LightUpCellType type) {
+    public int getNumAdj(@NotNull LightUpCell cell, @NotNull LightUpCellType type) {
         int num = 0;
         Set<LightUpCell> adjCells = getAdj(cell);
         for (LightUpCell c : adjCells) {
@@ -134,7 +136,7 @@ public int getNumAdj(LightUpCell cell, LightUpCellType type) {
      * @param cell LightUpCell
      * @return number of adjacent cells
      */
-    public int getNumAdjLite(LightUpCell cell) {
+    public int getNumAdjLite(@NotNull LightUpCell cell) {
         int num = 0;
         Set<LightUpCell> adjCells = getAdj(cell);
         for (LightUpCell c : adjCells) {
@@ -151,7 +153,7 @@ public int getNumAdjLite(LightUpCell cell) {
      * @param cell specified cell
      * @return number of adjacent cells that are placeable
      */
-    public int getNumPlaceable(LightUpCell cell) {
+    public int getNumPlaceable(@NotNull LightUpCell cell) {
         int num = 0;
         Set<LightUpCell> adjCells = getAdj(cell);
         for (LightUpCell c : adjCells) {
@@ -170,7 +172,7 @@ public int getNumPlaceable(LightUpCell cell) {
      * @return cell at location x, y
      */
     @Override
-    public LightUpCell getCell(int x, int y) {
+    public @Nullable LightUpCell getCell(int x, int y) {
         return (LightUpCell) super.getCell(x, y);
     }
 
@@ -180,7 +182,7 @@ public LightUpCell getCell(int x, int y) {
      * @param puzzleElement the puzzle element that has changed
      */
     @Override
-    public void notifyChange(PuzzleElement puzzleElement) {
+    public void notifyChange(@NotNull PuzzleElement puzzleElement) {
         super.notifyChange(puzzleElement);
         fillWithLight();
     }
@@ -191,7 +193,7 @@ public void notifyChange(PuzzleElement puzzleElement) {
      * @return a new copy of the LightUpBoard that is independent of this one
      */
     @Override
-    public LightUpBoard copy() {
+    public @NotNull LightUpBoard copy() {
         LightUpBoard copy = new LightUpBoard(dimension.width, dimension.height);
         for (int x = 0; x < this.dimension.width; x++) {
             for (int y = 0; y < this.dimension.height; y++) {
@@ -204,4 +206,4 @@ public LightUpBoard copy() {
         copy.fillWithLight();
         return copy;
     }
-}
+}