Documented code & improved code style.

- JavaDoc added for all classes, methods and fields.
- Checkstyle errors fixed
- Minor code style improvements & checks added.

Author: timlg07

Sudoku-Solver/src/sudoku/gui/GameBoardPanel.java

@@ -16,6 +16,9 @@
 import sudoku.util.Observable;
 import sudoku.util.Observer;
 
+/**
+ * This class handles the graphical representation of a sudoku board.
+ */
 public class GameBoardPanel extends Container implements Observer {
 
     private static final long serialVersionUID = 770590847429244978L;
@@ -26,9 +29,14 @@ public class GameBoardPanel extends Container implements Observer {
     private static final Border BOX_BORDER 
             = BorderFactory.createBevelBorder(BevelBorder.LOWERED);
 
+    /**
+     * All cells of the sudoku board.
+     */
     private final List<SudokuCell> cells = new ArrayList<>();
 
     /**
+     * Creates a new {@code GameBoardPanel} that gets updated if the given data
+     * model changes.
      * 
      * @param data The board data that should be visualized, not {@code null}.
      */
@@ -76,6 +84,9 @@ public GameBoardPanel(DisplayData data) {
         }
     }
 
+    /**
+     * Updates the values of all cells in this board.
+     */
     @Override
     public void update(Observable observable, Object argument) {
         /*
@@ -86,6 +97,14 @@ public void update(Observable observable, Object argument) {
         cells.forEach(SudokuCell::updateValue);
     }
 
+    /**
+     * Enables or disables the popup menus of all cells in this board. 
+     * This should be used to prevent modification of the sudoku board during 
+     * ongoing operations on it.
+     * 
+     * @param enabled Whether the popup menus should be set to enabled or 
+     *                disabled.
+     */
     public void setPopupsEnabled(boolean enabled) {
         cells.forEach(c -> c.setPopupMenuEnabled(enabled));
     }

Sudoku-Solver/src/sudoku/gui/SudokuCell.java

@@ -16,10 +16,12 @@
 
 import sudoku.gui.model.DisplayData;
 
+/**
+ * This class models a cell of a graphically visible sudoku board.
+ */
 public class SudokuCell extends JLabel {
-
-    private static final long serialVersionUID = 1L;
 
+    private static final long serialVersionUID = 7427321882456642556L;
 
     /**
      * The foreground color each unmodifiable cell should have.
@@ -38,21 +40,46 @@ public class SudokuCell extends JLabel {
      */
     private static final int FONT_SIZE = 14;
 
+    /**
+     * The major index of the position this cell has in the board.
+     */
     private final int majorIndex;
+    
+    /**
+     * The minor index of the position this cell has in the board.
+     */
     private final int minorIndex;
+    
+    /**
+     * The data model that is visualized by the board this cell is a part of.
+     */
     private final DisplayData data;
+    
+    /**
+     * The popup menu the user can use to change the cells value.
+     */
     private final JPopupMenu popupMenu;
 
+    /**
+     * Creates a new cell at the given position that shows the value of the 
+     * given data model at the same position. Unmodifiable cells are highlighted
+     * and have no popup menu.
+     * 
+     * @param major The major coordinate of this cell.
+     * @param minor The minor coordinate of this cell.
+     * @param data The data model where the values are stored.
+     * @param isModifiable Whether this cell can be modified or not.
+     */
     public SudokuCell(
             int major, int minor, DisplayData data, boolean isModifiable) {
         super("", SwingConstants.CENTER);
+        
         majorIndex = major;
         minorIndex = minor;
         this.data = data;
 
         if (isModifiable) {
             popupMenu = new CellPopupMenu();
-            setComponentPopupMenu(popupMenu);
         } else {
             popupMenu = null;
             setForeground(FIXED_CELL_COLOR);
@@ -64,8 +91,11 @@ public SudokuCell(
         setBorder(CELL_BORDER);
     }
 
+    /**
+     * Sets the preferred and minimum size of this cell depending on the font
+     * size of the cell.
+     */
     private void setDimensions() {
-        // maybe constant size but lower the font size?
         int maxDigits = (int) (Math.log10(data.getNumbers()) + 1);
         int contentSize = maxDigits * FONT_SIZE;
         int sizeWithPadding = contentSize + (FONT_SIZE * 2);
@@ -74,15 +104,24 @@ private void setDimensions() {
         setMinimumSize(new Dimension(contentSize, contentSize));
     }
 
+    /**
+     * Enables or disables the popup menu that is used to change the cells 
+     * value.
+     * 
+     * @param enabled Whether the popup menu should be enabled or disabled.
+     */
     void setPopupMenuEnabled(boolean enabled) {
-        // popupMenu.setEnabled(enabled);
         if (enabled) {
             setComponentPopupMenu(popupMenu);
         } else {
             setComponentPopupMenu(null);
         }
     }
 
+    /**
+     * Updates the value of this cell to the value currently stored in the data
+     * model.
+     */
     void updateValue() {
         int value = data.getCell(majorIndex, minorIndex);
         String displayValue = (value == DisplayData.UNSET_CELL) 
@@ -92,11 +131,18 @@ void updateValue() {
     }
 
 
-    private class CellPopupMenu extends JPopupMenu {
-        
-        private static final long serialVersionUID = 1L;
+    /**
+     * This class models the custom popup menu of a cell.
+     */
+    private final class CellPopupMenu extends JPopupMenu {
+
+        private static final long serialVersionUID = 5643550068619328847L;
 
-        public CellPopupMenu() {
+        /**
+         * Creates a new popup menu with the numbers a cell can be set to and a
+         * option to remove the stored value from a cell.
+         */
+        private CellPopupMenu() {
             for (int i = 1; i <= data.getNumbers(); i++) {
                 JMenuItem item = add(Integer.toString(i));
                 item.addActionListener(new ChangeCellActionListener(i));
@@ -107,14 +153,33 @@ public CellPopupMenu() {
                     new ChangeCellActionListener(DisplayData.UNSET_CELL));
         }
 
-        private class ChangeCellActionListener implements ActionListener {
+        /**
+         * The listener for change cell actions of the user. This listener can
+         * change the value of a cell in the data model to its assigned value.
+         */
+        private final class ChangeCellActionListener implements ActionListener {
 
+            /**
+             * The value this listener was created for.
+             */
             private final int assignedValue;
 
-            public ChangeCellActionListener(int assignedValue) {
+            /**
+             * Creates a new {@code ChangeCellActionListener} which should
+             * listen for the selection of the assigned value. When this action
+             * is performed, the cells value in the data model gets updated to
+             * the assigned value.
+             *  
+             * @param assignedValue The value this listener is responsible for.
+             */
+            private ChangeCellActionListener(int assignedValue) {
                 this.assignedValue = assignedValue;
             }
 
+            /**
+             * Sets the value of the cell which this listener was created for to
+             * the value that was assigned to this listener.
+             */
             @Override
             public void actionPerformed(ActionEvent e) {
                 data.setCell(majorIndex, minorIndex, assignedValue);

Sudoku-Solver/src/sudoku/gui/SudokuDialogMessages.java

@@ -6,15 +6,27 @@
 
 import sudoku.gui.model.DisplayData;
 
+/**
+ * This class contains static methods used to show the same messages from 
+ * different classes.
+ */
 public final class SudokuDialogMessages {
 
     /** 
-     * Private constructor to prevent instantiation. 
+     * Private constructor to prevent instantiation.
      */
     private SudokuDialogMessages() {
-        throw new AssertionError();
+        throw new AssertionError("This class should not be instantiated.");
     }
 
+    /**
+     * If the given data model is completely filled, a message is shown which
+     * informs the user about whether the sudoku is a valid solution or not.
+     *  
+     * @param parent Determines the Frame in which the dialog is displayed.
+     * @param data The data model that should be checked if it is full and
+     *             solved.
+     */
     public static void showMessageIfFilled(Component parent, DisplayData data) {
         if (data.isFilled()) {
             String message;
@@ -26,23 +38,49 @@ public static void showMessageIfFilled(Component parent, DisplayData data) {
             JOptionPane.showMessageDialog(parent, message);
         }
     }
-    
-    public static void showError(Component parent, String title, String message) {
-        JOptionPane.showMessageDialog(
-                parent, message, title, JOptionPane.ERROR_MESSAGE);
-    }
 
+    /**
+     * Shows an error message that informs the user about an invalid sudoku.
+     * 
+     * @param parent Determines the Frame in which the dialog is displayed.
+     */
     public static void showErrorInvalid(Component parent) {
         showError(parent, "Invalid sudoku", "The current sudoku is invalid.");
     }
 
+    /**
+     * Shows an error message that informs the user about a sudoku that cannot
+     * be solved by the program.
+     * 
+     * @param parent Determines the Frame in which the dialog is displayed.
+     */
     public static void showErrorUnsolvable(Component parent) {
         showError(parent, "Unsolvable sudoku", 
-                "This operation cannot be performed on an unsolvable sudoku.");
+                "The current sudoku is not solvable.");
     }
 
+    /**
+     * Shows an error message that informs the user that the sudoku is already
+     * filled and a suggestion cannot be made on it.
+     * 
+     * @param parent Determines the Frame in which the dialog is displayed.
+     */
     public static void showErrorAlreadyFilled(Component parent) {
         showError(parent, "No empty cells", 
                 "Cannot suggest a value if all cells are set.");
     }
+    
+    /**
+     * Shows a error message with an option pane dialog. The given parameters
+     * are used for displaying the message dialog.
+     * 
+     * @param parent Determines the Frame in which the dialog is displayed.
+     * @param title The title of the error message.
+     * @param message The description of the error message.
+     */
+    private static void showError(
+            Component parent, String title, String message) {
+        JOptionPane.showMessageDialog(
+                parent, message, title, JOptionPane.ERROR_MESSAGE);
+    }
 }