Mercurial > hg > Sudoku / changeset

     1.1 --- a/src/main/java/de/uapcore/sudoku/ActionHandler.java	Sat Jul 25 14:01:28 2020 +0200
     1.2 +++ b/src/main/java/de/uapcore/sudoku/ActionHandler.java	Sat Jul 25 15:29:51 2020 +0200
     1.3 @@ -1,16 +1,16 @@
     1.4  /*
     1.5   * Copyright 2013 Mike Becker. All rights reserved.
     1.6 - * 
     1.7 + *
     1.8   * Redistribution and use in source and binary forms, with or without
     1.9   * modification, are permitted provided that the following conditions are met:
    1.10 - * 
    1.11 + *
    1.12   * 1. Redistributions of source code must retain the above copyright
    1.13   *    notice, this list of conditions and the following disclaimer.
    1.14 - * 
    1.15 + *
    1.16   * 2. Redistributions in binary form must reproduce the above copyright
    1.17   *    notice, this list of conditions and the following disclaimer in the
    1.18   *    documentation and/or other materials provided with the distribution.
    1.19 - * 
    1.20 + *
    1.21   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    1.22   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    1.23   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    1.24 @@ -33,31 +33,42 @@
    1.25  import java.io.IOException;
    1.26  
    1.27  /**
    1.28 - *
    1.29 - * @author mike
    1.30 + * Handles all user issued actions in the application.
    1.31   */
    1.32  public final class ActionHandler implements ActionListener {
    1.33 -    
    1.34 +
    1.35      public static final String SAVE = "save";
    1.36      public static final String CHECK = "check";
    1.37      public static final String SOLVE = "solve";
    1.38 -    
    1.39 +
    1.40      public static final String NEW = "new";
    1.41      public static final String OPEN = "open";
    1.42      public static final String SAVE_AS = "save as";
    1.43      public static final String QUIT = "quit";
    1.44      public static final String ABOUT = "about";
    1.45 -    
    1.46 +
    1.47      private Field field;
    1.48      private Solver solver;
    1.49      private DocumentHandler doc;
    1.50 -    
    1.51 +
    1.52 +    /**
    1.53 +     * Constructs a new action handler instance.
    1.54 +     *
    1.55 +     * @param f a reference to the playing field
    1.56 +     */
    1.57      public ActionHandler(Field f) {
    1.58          field = f;
    1.59          solver = new Solver();
    1.60          doc = new DocumentHandler();
    1.61      }
    1.62 -    
    1.63 +
    1.64 +    /**
    1.65 +     * Prompts the user for a file name.
    1.66 +     * <p>
    1.67 +     * If the user chooses an existing file, they are asked whether the file should be overwritten.
    1.68 +     *
    1.69 +     * @return true if the user approves a chosen file name
    1.70 +     */
    1.71      private boolean chooseSaveFilename() {
    1.72          JFileChooser fc = new JFileChooser(".");
    1.73          fc.setMultiSelectionEnabled(false);
    1.74 @@ -81,7 +92,10 @@
    1.75              return false;
    1.76          }
    1.77      }
    1.78 -    
    1.79 +
    1.80 +    /**
    1.81 +     * Prompts the user for a file to open and, if approved, loads that file.
    1.82 +     */
    1.83      private void open() {
    1.84          JFileChooser fc = new JFileChooser(".");
    1.85          fc.setMultiSelectionEnabled(false);
    1.86 @@ -92,12 +106,22 @@
    1.87                  doc.load(field);
    1.88              } catch (IOException e) {
    1.89                  JOptionPane.showMessageDialog(field,
    1.90 -                    "Datei konnte nicht geladen werden: "+e.getMessage(),
    1.91 -                    "Sudoku", JOptionPane.ERROR_MESSAGE);
    1.92 +                        "Datei konnte nicht geladen werden: " + e.getMessage(),
    1.93 +                        "Sudoku", JOptionPane.ERROR_MESSAGE);
    1.94              }
    1.95          }
    1.96      }
    1.97 -    
    1.98 +
    1.99 +    /**
   1.100 +     * Attempts to save the Sudoku field to a file.
   1.101 +     * <p>
   1.102 +     * If necessary, the user is prompted for a file name.
   1.103 +     * <p>
   1.104 +     * The field must be solvable, otherwise it cannot be saved.
   1.105 +     *
   1.106 +     * @param rename true if the user shall always be prompted, even if a file name is already known
   1.107 +     * @return true if the user approves the chosen file name
   1.108 +     */
   1.109      private boolean save(boolean rename) {
   1.110          if (!doc.isFilenameSet() || rename) {
   1.111              if (!chooseSaveFilename()) {
   1.112 @@ -110,8 +134,8 @@
   1.113                  doc.save(field);
   1.114              } catch (IOException e) {
   1.115                  JOptionPane.showMessageDialog(field,
   1.116 -                    "Datei konnte nicht gespeichert werden: "+e.getMessage(),
   1.117 -                    "Sudoku", JOptionPane.ERROR_MESSAGE);
   1.118 +                        "Datei konnte nicht gespeichert werden: " + e.getMessage(),
   1.119 +                        "Sudoku", JOptionPane.ERROR_MESSAGE);
   1.120              }
   1.121              return true;
   1.122          } else {
   1.123 @@ -121,7 +145,10 @@
   1.124              return false;
   1.125          }
   1.126      }
   1.127 -    
   1.128 +
   1.129 +    /**
   1.130 +     * Checks the Sudoku field and displays the result as a dialog box.
   1.131 +     */
   1.132      private void check() {
   1.133          if (solver.check(field)) {
   1.134              JOptionPane.showMessageDialog(field, "Überprüfung erfolgreich!",
   1.135 @@ -131,14 +158,22 @@
   1.136                      "Sudoku", JOptionPane.WARNING_MESSAGE);
   1.137          }
   1.138      }
   1.139 -    
   1.140 +
   1.141 +    /**
   1.142 +     * Solves the field or displays an error dialog if the field is not solvable.
   1.143 +     */
   1.144      private void solve() {
   1.145          if (!solver.check(field) || !solver.solve(field)) {
   1.146              JOptionPane.showMessageDialog(field, "Das Feld ist nicht lösbar!",
   1.147                      "Sudoku", JOptionPane.WARNING_MESSAGE);
   1.148          }
   1.149      }
   1.150 -    
   1.151 +
   1.152 +    /**
   1.153 +     * Checks whether there are unsaved changes and asks the user to save the field.
   1.154 +     *
   1.155 +     * @return true if there are no unsaved changes or the user actively decides to continue - false, otherwise
   1.156 +     */
   1.157      private boolean saveUnsaved() {
   1.158          boolean proceed = false;
   1.159          if (field.isAnyCellModified()) {
   1.160 @@ -155,49 +190,49 @@
   1.161          } else {
   1.162              proceed = true;
   1.163          }
   1.164 -        
   1.165 +
   1.166          return proceed;
   1.167      }
   1.168  
   1.169      @Override
   1.170      public void actionPerformed(ActionEvent e) {
   1.171          switch (e.getActionCommand()) {
   1.172 -        case NEW:
   1.173 -            if (saveUnsaved()) {
   1.174 -                doc.clearFilename();
   1.175 -                field.clear();
   1.176 -            }
   1.177 -            break;
   1.178 -        case OPEN:
   1.179 -            open();
   1.180 -            break;
   1.181 -        case SAVE:
   1.182 -            save(false);
   1.183 -            break;
   1.184 -        case SAVE_AS:
   1.185 -            save(true);
   1.186 -            break;
   1.187 -        case CHECK:
   1.188 -            check();
   1.189 -            break;
   1.190 -        case SOLVE:
   1.191 -            solve();
   1.192 -            break;
   1.193 -        case QUIT:
   1.194 -            if (saveUnsaved()) {
   1.195 -                System.exit(0);
   1.196 -            }
   1.197 -            break;
   1.198 -        case ABOUT:
   1.199 -            JOptionPane.showMessageDialog(field,
   1.200 -                    "Sudoku - Copyright (c) 2013 Mike Becker\nwww.uap-core.de"+
   1.201 -                    "\nPublished under the BSD License",
   1.202 -                    "Sudoku", JOptionPane.INFORMATION_MESSAGE);
   1.203 -            break;
   1.204 -        default:
   1.205 -            throw new UnsupportedOperationException(
   1.206 -                    "unknown action: "+e.getActionCommand());
   1.207 +            case NEW:
   1.208 +                if (saveUnsaved()) {
   1.209 +                    doc.clearFilename();
   1.210 +                    field.clear();
   1.211 +                }
   1.212 +                break;
   1.213 +            case OPEN:
   1.214 +                open();
   1.215 +                break;
   1.216 +            case SAVE:
   1.217 +                save(false);
   1.218 +                break;
   1.219 +            case SAVE_AS:
   1.220 +                save(true);
   1.221 +                break;
   1.222 +            case CHECK:
   1.223 +                check();
   1.224 +                break;
   1.225 +            case SOLVE:
   1.226 +                solve();
   1.227 +                break;
   1.228 +            case QUIT:
   1.229 +                if (saveUnsaved()) {
   1.230 +                    System.exit(0);
   1.231 +                }
   1.232 +                break;
   1.233 +            case ABOUT:
   1.234 +                JOptionPane.showMessageDialog(field,
   1.235 +                        "Sudoku - Copyright (c) 2013 Mike Becker\nwww.uap-core.de" +
   1.236 +                                "\nPublished under the BSD License",
   1.237 +                        "Sudoku", JOptionPane.INFORMATION_MESSAGE);
   1.238 +                break;
   1.239 +            default:
   1.240 +                throw new UnsupportedOperationException(
   1.241 +                        "unknown action: " + e.getActionCommand());
   1.242          }
   1.243      }
   1.244 -    
   1.245 +
   1.246  }

     2.1 --- a/src/main/java/de/uapcore/sudoku/ButtonPanel.java	Sat Jul 25 14:01:28 2020 +0200
     2.2 +++ b/src/main/java/de/uapcore/sudoku/ButtonPanel.java	Sat Jul 25 15:29:51 2020 +0200
     2.3 @@ -30,8 +30,7 @@
     2.4  import java.awt.*;
     2.5  
     2.6  /**
     2.7 - *
     2.8 - * @author mike
     2.9 + * The panel displaying some actions for the Sudoku solver.
    2.10   */
    2.11  public final class ButtonPanel extends JPanel {
    2.12      

     3.1 --- a/src/main/java/de/uapcore/sudoku/DocumentHandler.java	Sat Jul 25 14:01:28 2020 +0200
     3.2 +++ b/src/main/java/de/uapcore/sudoku/DocumentHandler.java	Sat Jul 25 15:29:51 2020 +0200
     3.3 @@ -32,12 +32,18 @@
     3.4  
     3.5  /**
     3.6   *
     3.7 - * @author mike
     3.8   */
     3.9  public class DocumentHandler {
    3.10      
    3.11      private String filename;
    3.12 -    
    3.13 +
    3.14 +    /**
    3.15 +     * Loads data into the specified field.
    3.16 +     *
    3.17 +     * @param field the field to populated with the loaded data
    3.18 +     * @throws IOException if loading fails or no file name has been set before
    3.19 +     * @see #setFilename(String)
    3.20 +     */
    3.21      public void load(Field field) throws IOException {
    3.22          if (!isFilenameSet()) {
    3.23              throw new IOException("no filename supplied");
    3.24 @@ -72,7 +78,14 @@
    3.25          }
    3.26          field.setAllCellsModified(false);
    3.27      }
    3.28 -    
    3.29 +
    3.30 +    /**
    3.31 +     * Saves the specified field to a file.
    3.32 +     *
    3.33 +     * @param field the field to save
    3.34 +     * @throws IOException if saving fails or the file name has not been set before
    3.35 +     * @see #setFilename(String)
    3.36 +     */
    3.37      public void save(Field field) throws IOException {
    3.38          if (!isFilenameSet()) {
    3.39              throw new IOException("no filename supplied");
    3.40 @@ -89,15 +102,28 @@
    3.41              }
    3.42          }
    3.43      }
    3.44 -    
    3.45 +
    3.46 +    /**
    3.47 +     * Sets the file name for loading and saving data.
    3.48 +     *
    3.49 +     * @param filename the file name
    3.50 +     */
    3.51      public void setFilename(String filename) {
    3.52          this.filename = filename;
    3.53      }
    3.54 -    
    3.55 +
    3.56 +    /**
    3.57 +     * Clears the file name.
    3.58 +     */
    3.59      public void clearFilename() {
    3.60          filename = null;
    3.61      }
    3.62 -    
    3.63 +
    3.64 +    /**
    3.65 +     * Checks whether a file name has been set.
    3.66 +     *
    3.67 +     * @return true if a file name is known, false otherwise
    3.68 +     */
    3.69      public boolean isFilenameSet() {
    3.70          return filename != null;
    3.71      }

     4.1 --- a/src/main/java/de/uapcore/sudoku/Field.java	Sat Jul 25 14:01:28 2020 +0200
     4.2 +++ b/src/main/java/de/uapcore/sudoku/Field.java	Sat Jul 25 15:29:51 2020 +0200
     4.3 @@ -1,16 +1,16 @@
     4.4  /*
     4.5   * Copyright 2013 Mike Becker. All rights reserved.
     4.6 - * 
     4.7 + *
     4.8   * Redistribution and use in source and binary forms, with or without
     4.9   * modification, are permitted provided that the following conditions are met:
    4.10 - * 
    4.11 + *
    4.12   * 1. Redistributions of source code must retain the above copyright
    4.13   *    notice, this list of conditions and the following disclaimer.
    4.14 - * 
    4.15 + *
    4.16   * 2. Redistributions in binary form must reproduce the above copyright
    4.17   *    notice, this list of conditions and the following disclaimer in the
    4.18   *    documentation and/or other materials provided with the distribution.
    4.19 - * 
    4.20 + *
    4.21   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
    4.22   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    4.23   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    4.24 @@ -31,22 +31,26 @@
    4.25  import java.awt.image.BufferedImage;
    4.26  
    4.27  /**
    4.28 - *
    4.29 - * @author mike
    4.30 + * A panel rendering the Sudoku field.
    4.31 + * <p>
    4.32 + * Cells are identified by zero-based indices from top-left to bottom-right.
    4.33   */
    4.34  public final class Field extends JPanel {
    4.35      private SudokuTextField[][] cells;
    4.36 -    
    4.37 +
    4.38 +    /**
    4.39 +     * Constructs a new 9x9 Sudoku grid.
    4.40 +     */
    4.41      public Field() {
    4.42          setBackground(Color.WHITE);
    4.43 -        
    4.44 +
    4.45          setLayout(new GridBagLayout());
    4.46          GridBagConstraints c = new GridBagConstraints();
    4.47          c.insets = new Insets(5, 5, 5, 5);
    4.48 -        
    4.49 +
    4.50          cells = new SudokuTextField[9][9];
    4.51 -        for (int x = 0 ; x < 9 ; x++) {
    4.52 -            for (int y = 0 ; y < 9 ; y++) {
    4.53 +        for (int x = 0; x < 9; x++) {
    4.54 +            for (int y = 0; y < 9; y++) {
    4.55                  cells[x][y] = new SudokuTextField();
    4.56                  c.gridx = x;
    4.57                  c.gridy = y;
    4.58 @@ -55,69 +59,118 @@
    4.59          }
    4.60      }
    4.61  
    4.62 +    /**
    4.63 +     * Paints the grid and all contained cells.
    4.64 +     *
    4.65 +     * @param graphics the graphics context
    4.66 +     */
    4.67      @Override
    4.68      public void paint(Graphics graphics) {
    4.69          final int w = getWidth();
    4.70          final int h = getHeight();
    4.71          final int cw = w / 9;
    4.72          final int ch = h / 9;
    4.73 -        
    4.74 +
    4.75          BufferedImage img = new BufferedImage(w, h, BufferedImage.TYPE_INT_RGB);
    4.76          Graphics2D g = img.createGraphics();
    4.77          g.setBackground(Color.WHITE);
    4.78          g.clearRect(0, 0, w, h);
    4.79 -        
    4.80 +
    4.81          g.setColor(Color.BLACK);
    4.82 -        g.drawRect(1, 1, w-2, h-2);
    4.83 -        g.drawRect(2, 2, w-4, h-4);
    4.84 -        for (int x = cw ; x < w ; x += cw) {
    4.85 -            for (int y = ch ; y < h ; y += ch) {
    4.86 -                g.drawLine(x, 2, x, h-2);
    4.87 -                g.drawLine(2, y, w-2, y);
    4.88 +        g.drawRect(1, 1, w - 2, h - 2);
    4.89 +        g.drawRect(2, 2, w - 4, h - 4);
    4.90 +        for (int x = cw; x < w; x += cw) {
    4.91 +            for (int y = ch; y < h; y += ch) {
    4.92 +                g.drawLine(x, 2, x, h - 2);
    4.93 +                g.drawLine(2, y, w - 2, y);
    4.94                  if ((x / cw) % 3 == 0) {
    4.95 -                    g.drawLine(x+1, 2, x+1, h-2);
    4.96 +                    g.drawLine(x + 1, 2, x + 1, h - 2);
    4.97                  }
    4.98                  if ((y / ch) % 3 == 0) {
    4.99 -                    g.drawLine(2, y+1, w-2, y+1);
   4.100 +                    g.drawLine(2, y + 1, w - 2, y + 1);
   4.101                  }
   4.102              }
   4.103          }
   4.104 -        
   4.105 +
   4.106          graphics.drawImage(img, 0, 0, this);
   4.107          super.paintChildren(graphics);
   4.108      }
   4.109 -    
   4.110 +
   4.111 +    /**
   4.112 +     * Checks whether a cell is empty
   4.113 +     *
   4.114 +     * @param x horizontal position
   4.115 +     * @param y vertical position
   4.116 +     * @return true if the cell is empty, false otherwise
   4.117 +     */
   4.118      public boolean isCellEmpty(int x, int y) {
   4.119          return getCellValue(x, y) == 0;
   4.120      }
   4.121 -    
   4.122 +
   4.123 +    /**
   4.124 +     * Returns value of a specific cell.
   4.125 +     *
   4.126 +     * @param x horizontal position
   4.127 +     * @param y vertical position
   4.128 +     * @return the cell's value
   4.129 +     */
   4.130      public int getCellValue(int x, int y) {
   4.131          return cells[x][y].getValue();
   4.132      }
   4.133 -    
   4.134 +
   4.135 +    /**
   4.136 +     * Sets the value of a specific cell.
   4.137 +     *
   4.138 +     * @param x horizontal position
   4.139 +     * @param y vertical position
   4.140 +     * @param v the cells value
   4.141 +     */
   4.142      public void setCellValue(int x, int y, int v) {
   4.143          cells[x][y].setValue(v);
   4.144      }
   4.145 -    
   4.146 +
   4.147 +    /**
   4.148 +     * Clears the value of a specific cell.
   4.149 +     *
   4.150 +     * @param x horizontal position
   4.151 +     * @param y vertical position
   4.152 +     */
   4.153      public void clearCellValue(int x, int y) {
   4.154          setCellValue(x, y, 0);
   4.155      }
   4.156 -    
   4.157 +
   4.158 +    /**
   4.159 +     * Sets the modified state of a specific cell.
   4.160 +     *
   4.161 +     * @param x        horizontal position
   4.162 +     * @param y        vertical position
   4.163 +     * @param modified the modified state
   4.164 +     */
   4.165      public void setCellModified(int x, int y, boolean modified) {
   4.166          cells[x][y].setModified(modified);
   4.167      }
   4.168 -    
   4.169 +
   4.170 +    /**
   4.171 +     * Sets the modified state of all cells.
   4.172 +     *
   4.173 +     * @param modified the modified state
   4.174 +     */
   4.175      public void setAllCellsModified(boolean modified) {
   4.176 -        for (int x = 0 ; x < 9 ; x++) {
   4.177 -            for (int y = 0 ; y < 9 ; y++) {
   4.178 +        for (int x = 0; x < 9; x++) {
   4.179 +            for (int y = 0; y < 9; y++) {
   4.180                  cells[x][y].setModified(modified);
   4.181              }
   4.182          }
   4.183      }
   4.184 -    
   4.185 +
   4.186 +    /**
   4.187 +     * Checks whether any cell is modified.
   4.188 +     *
   4.189 +     * @return true if any cell is modified, false otherwise
   4.190 +     */
   4.191      public boolean isAnyCellModified() {
   4.192 -        for (int x = 0 ; x < 9 ; x++) {
   4.193 -            for (int y = 0 ; y < 9 ; y++) {
   4.194 +        for (int x = 0; x < 9; x++) {
   4.195 +            for (int y = 0; y < 9; y++) {
   4.196                  if (cells[x][y].isModified()) {
   4.197                      return true;
   4.198                  }
   4.199 @@ -125,53 +178,77 @@
   4.200          }
   4.201          return false;
   4.202      }
   4.203 -    
   4.204 +
   4.205 +    /**
   4.206 +     * Clears all cells.
   4.207 +     */
   4.208      public void clear() {
   4.209 -        for (int x = 0 ; x < 9 ; x++) {
   4.210 -            for (int y = 0 ; y < 9 ; y++) {
   4.211 +        for (int x = 0; x < 9; x++) {
   4.212 +            for (int y = 0; y < 9; y++) {
   4.213                  cells[x][y].setValue(0);
   4.214              }
   4.215          }
   4.216      }
   4.217 -    
   4.218 +
   4.219 +    /**
   4.220 +     * Returns a square identified by square coordinates.
   4.221 +     * <p>
   4.222 +     * Cells within the square are identified by the same coordinate system.
   4.223 +     *
   4.224 +     * @param x horizontal position from 0 to 2
   4.225 +     * @param y vertical position from 0 to 2
   4.226 +     * @return a two-dimensional array containing the square cell values
   4.227 +     */
   4.228      public int[][] getSquare(int x, int y) {
   4.229          if (x < 0 || x > 2 || y < 0 || y > 2) {
   4.230              throw new IllegalArgumentException("Invalid square coordinates");
   4.231          }
   4.232          int[][] square = new int[3][3];
   4.233 -        
   4.234 -        for (int u = 0 ; u < 3 ; u++) {
   4.235 -            for (int v = 0 ; v < 3 ; v++) {
   4.236 -                square[u][v] = getCellValue(3*x+u, 3*y+v);
   4.237 +
   4.238 +        for (int u = 0; u < 3; u++) {
   4.239 +            for (int v = 0; v < 3; v++) {
   4.240 +                square[u][v] = getCellValue(3 * x + u, 3 * y + v);
   4.241              }
   4.242          }
   4.243 -        
   4.244 +
   4.245          return square;
   4.246      }
   4.247 -    
   4.248 +
   4.249 +    /**
   4.250 +     * Returns an entire row.
   4.251 +     *
   4.252 +     * @param y the row position
   4.253 +     * @return an array containing the row values
   4.254 +     */
   4.255      public int[] getRow(int y) {
   4.256          if (y < 0 || y > 8) {
   4.257              throw new IllegalArgumentException("Invalid row number");
   4.258          }
   4.259          int row[] = new int[9];
   4.260 -        
   4.261 -        for (int x = 0 ; x < 9 ; x++) {
   4.262 +
   4.263 +        for (int x = 0; x < 9; x++) {
   4.264              row[x] = getCellValue(x, y);
   4.265          }
   4.266 -        
   4.267 +
   4.268          return row;
   4.269      }
   4.270 -    
   4.271 +
   4.272 +    /**
   4.273 +     * Returns an entire column
   4.274 +     *
   4.275 +     * @param x the column position
   4.276 +     * @return an array containing the column values
   4.277 +     */
   4.278      public int[] getColumn(int x) {
   4.279          if (x < 0 || x > 8) {
   4.280              throw new IllegalArgumentException("Invalid column number");
   4.281          }
   4.282          int column[] = new int[9];
   4.283 -        
   4.284 -        for (int y = 0 ; y < 9 ; y++) {
   4.285 +
   4.286 +        for (int y = 0; y < 9; y++) {
   4.287              column[y] = getCellValue(x, y);
   4.288          }
   4.289 -        
   4.290 +
   4.291          return column;
   4.292      }
   4.293  }

     5.1 --- a/src/main/java/de/uapcore/sudoku/MainMenu.java	Sat Jul 25 14:01:28 2020 +0200
     5.2 +++ b/src/main/java/de/uapcore/sudoku/MainMenu.java	Sat Jul 25 15:29:51 2020 +0200
     5.3 @@ -29,8 +29,7 @@
     5.4  import javax.swing.*;
     5.5  
     5.6  /**
     5.7 - *
     5.8 - * @author mike
     5.9 + * Main menu bar.
    5.10   */
    5.11  public class MainMenu {
    5.12      

     6.1 --- a/src/main/java/de/uapcore/sudoku/Solver.java	Sat Jul 25 14:01:28 2020 +0200
     6.2 +++ b/src/main/java/de/uapcore/sudoku/Solver.java	Sat Jul 25 15:29:51 2020 +0200
     6.3 @@ -30,14 +30,10 @@
     6.4  import java.util.List;
     6.5  
     6.6  /**
     6.7 - *
     6.8 - * @author mike
     6.9 + * Implements the backtracking algorithm for solving the Sudoku.
    6.10   */
    6.11  public final class Solver {
    6.12 -    
    6.13 -    public Solver() {
    6.14 -    }
    6.15 -    
    6.16 +
    6.17      private Integer fillInCandidate(Field f, List<Integer>[][] candidates, int x, int y) {
    6.18          Integer c = candidates[x][y].remove(0);
    6.19          f.setCellValue(x, y, c);
    6.20 @@ -138,7 +134,17 @@
    6.21          
    6.22          return true;
    6.23      }
    6.24 -    
    6.25 +
    6.26 +    /**
    6.27 +     * Attempts to solve the given Sudoku field.
    6.28 +     *
    6.29 +     * The solution, if any, is directly entered into the field.
    6.30 +     * All solved fields will be in modified state.
    6.31 +     * The already given fields are left untouched.
    6.32 +     *
    6.33 +     * @param f the field to solve
    6.34 +     * @return true if a solution could be found, false if the field is unsolvable
    6.35 +     */
    6.36      public boolean solve(Field f) {
    6.37          
    6.38          // Calculate initial candidates
    6.39 @@ -175,7 +181,13 @@
    6.40          // Backtrack
    6.41          return solve(f, candidates);
    6.42      }
    6.43 -    
    6.44 +
    6.45 +    /**
    6.46 +     * Performs a fast check whether any field violates the Sudoku rules.
    6.47 +     *
    6.48 +     * @param f the field to check
    6.49 +     * @return true, if the check succeeds, false otherwise
    6.50 +     */
    6.51      public boolean check(Field f) {
    6.52          int line[];
    6.53          for (int i = 0 ; i < 9 ; i++) {

     7.1 --- a/src/main/java/de/uapcore/sudoku/Sudoku.java	Sat Jul 25 14:01:28 2020 +0200
     7.2 +++ b/src/main/java/de/uapcore/sudoku/Sudoku.java	Sat Jul 25 15:29:51 2020 +0200
     7.3 @@ -30,11 +30,13 @@
     7.4  import java.awt.*;
     7.5  
     7.6  /**
     7.7 - *
     7.8 - * @author mike
     7.9 + * Main class of the application.
    7.10   */
    7.11  public final class Sudoku extends JFrame {
    7.12 -    
    7.13 +
    7.14 +    /**
    7.15 +     * Constructs the Sudoku main window.
    7.16 +     */
    7.17      public Sudoku() {
    7.18          super("Sudoku");
    7.19          
    7.20 @@ -61,6 +63,8 @@
    7.21      }
    7.22  
    7.23      /**
    7.24 +     * Main method starting the Sudoku solver.
    7.25 +     *
    7.26       * @param args the command line arguments
    7.27       */
    7.28      public static void main(String[] args) {

     8.1 --- a/src/main/java/de/uapcore/sudoku/SudokuTextField.java	Sat Jul 25 14:01:28 2020 +0200
     8.2 +++ b/src/main/java/de/uapcore/sudoku/SudokuTextField.java	Sat Jul 25 15:29:51 2020 +0200
     8.3 @@ -34,8 +34,7 @@
     8.4  import java.awt.event.KeyEvent;
     8.5  
     8.6  /**
     8.7 - *
     8.8 - * @author mike
     8.9 + * A custom text field specifically for Sudoku number fields.
    8.10   */
    8.11  public final class SudokuTextField extends JTextField {
    8.12      
    8.13 @@ -105,15 +104,25 @@
    8.14              }
    8.15          });
    8.16      }
    8.17 -    
    8.18 +
    8.19 +    /**
    8.20 +     * Returns the current value in the field or zero if the field is empty.
    8.21 +     *
    8.22 +     * @return the number from 1 to 9 or zero if empty
    8.23 +     */
    8.24      public int getValue() {
    8.25 -        if (getText().length() > 0) {
    8.26 +        if (getText().isEmpty()) {
    8.27 +            return 0;
    8.28 +        } else {
    8.29              return Integer.valueOf(getText());
    8.30 -        } else {
    8.31 -            return 0;
    8.32          }
    8.33      }
    8.34 -    
    8.35 +
    8.36 +    /**
    8.37 +     * Sets the field's value.
    8.38 +     *
    8.39 +     * @param v the number from 1 to 9 or zero to clear the field
    8.40 +     */
    8.41      public void setValue(int v) {
    8.42          if (v == 0) {
    8.43              setText("");
    8.44 @@ -124,12 +133,24 @@
    8.45                      "Sudoku numbers must be in range 0-9 (0 means 'not set')");
    8.46          }
    8.47      }
    8.48 -    
    8.49 +
    8.50 +    /**
    8.51 +     * Sets the modified state of this field.
    8.52 +     *
    8.53 +     * Modified fields are displayed in blue color.
    8.54 +     *
    8.55 +     * @param modified a flag indicating whether this field is modified
    8.56 +     */
    8.57      public void setModified(boolean modified) {
    8.58          this.modified = modified;
    8.59          setForeground(modified?Color.BLUE:Color.BLACK);
    8.60      }
    8.61 -    
    8.62 +
    8.63 +    /**
    8.64 +     * Checks whether this field is in modified state.
    8.65 +     *
    8.66 +     * @return true if this field is modified
    8.67 +     */
    8.68      public boolean isModified() {
    8.69          return modified;
    8.70      }