Add function documentation in Sudoku.java

DIRECTORY.md

@@ -451,6 +451,8 @@
             * [TowerOfHanoi](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/others/TowerOfHanoi.java)
             * [TwoPointers](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/others/TwoPointers.java)
             * [Verhoeff](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/others/Verhoeff.java)
+          * Recursion
+            * [GenerateSubsets](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/Recursion/GenerateSubsets.java)
           * scheduling
             * [FCFSScheduling](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/scheduling/FCFSScheduling.java)
             * [PreemptivePriorityScheduling](https://github.com/TheAlgorithms/Java/blob/master/src/main/java/com/thealgorithms/scheduling/PreemptivePriorityScheduling.java)
@@ -893,6 +895,8 @@
             * [TestPrintMatrixInSpiralOrder](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/others/TestPrintMatrixInSpiralOrder.java)
             * [TwoPointersTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/others/TwoPointersTest.java)
             * [WorstFitCPUTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/others/WorstFitCPUTest.java)
+          * Recursion
+            * [GenerateSubsetsTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/Recursion/GenerateSubsetsTest.java)
           * scheduling
             * [FCFSSchedulingTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/scheduling/FCFSSchedulingTest.java)
             * [PreemptivePrioritySchedulingTest](https://github.com/TheAlgorithms/Java/blob/master/src/test/java/com/thealgorithms/scheduling/PreemptivePrioritySchedulingTest.java)

src/main/java/com/thealgorithms/others/Sudoku.java

@@ -1,33 +1,44 @@
 package com.thealgorithms.others;
 
+/**
+ * A class that provides methods to solve a 9x9 Sudoku puzzle using a backtracking approach.
+ * The Sudoku board is represented as a 2D array, and the methods are designed to
+ * check for safe placements of numbers, solve the puzzle recursively, and print the board.
+ */
 final class Sudoku {
+
     private Sudoku() {
     }
 
+    /**
+     * Checks if placing a number in a specific position on the Sudoku board is safe.
+     * The number is considered safe if it does not violate any of the Sudoku rules:
+     * - It should not be present in the same row.
+     * - It should not be present in the same column.
+     * - It should not be present in the corresponding 3x3 subgrid.
+     *
+     * @param board The current state of the Sudoku board.
+     * @param row   The row index where the number is to be placed.
+     * @param col   The column index where the number is to be placed.
+     * @param num   The number to be placed on the board.
+     * @return True if the placement is safe, otherwise false.
+     */
     public static boolean isSafe(int[][] board, int row, int col, int num) {
-        // Row has the unique (row-clash)
+        // Check the row for duplicates
         for (int d = 0; d < board.length; d++) {
-            // Check if the number we are trying to
-            // place is already present in
-            // that row, return false;
             if (board[row][d] == num) {
                 return false;
             }
         }
 
-        // Column has the unique numbers (column-clash)
+        // Check the column for duplicates
         for (int r = 0; r < board.length; r++) {
-            // Check if the number
-            // we are trying to
-            // place is already present in
-            // that column, return false;
             if (board[r][col] == num) {
                 return false;
             }
         }
 
-        // Corresponding square has
-        // unique number (box-clash)
+        // Check the corresponding 3x3 subgrid for duplicates
         int sqrt = (int) Math.sqrt(board.length);
         int boxRowStart = row - row % sqrt;
         int boxColStart = col - col % sqrt;
@@ -40,22 +51,31 @@ public static boolean isSafe(int[][] board, int row, int col, int num) {
             }
         }
 
-        // if there is no clash, it's safe
         return true;
     }
 
+    /**
+     * Solves the Sudoku puzzle using backtracking.
+     * The algorithm finds an empty cell and tries placing numbers from 1 to 9.
+     * If a number placement is valid (checked via `isSafe`), the number is placed and the function
+     * recursively attempts to solve the rest of the puzzle.
+     * If no solution is possible, the number is removed (backtracked), and the process is repeated.
+     *
+     * @param board The current state of the Sudoku board.
+     * @param n     The size of the Sudoku board (typically 9 for a standard puzzle).
+     * @return True if the Sudoku puzzle is solvable, false otherwise.
+     */
     public static boolean solveSudoku(int[][] board, int n) {
         int row = -1;
         int col = -1;
         boolean isEmpty = true;
+
+        // Find the next empty cell (marked by 0)
         for (int i = 0; i < n; i++) {
             for (int j = 0; j < n; j++) {
                 if (board[i][j] == 0) {
                     row = i;
                     col = j;
-
-                    // We still have some remaining
-                    // missing values in Sudoku
                     isEmpty = false;
                     break;
                 }
@@ -70,12 +90,11 @@ public static boolean solveSudoku(int[][] board, int n) {
             return true;
         }
 
-        // Else for each-row backtrack
+        // Try placing numbers 1 to 9 in the empty cell
         for (int num = 1; num <= n; num++) {
             if (isSafe(board, row, col, num)) {
                 board[row][col] = num;
                 if (solveSudoku(board, n)) {
-                    // print(board, n);
                     return true;
                 } else {
                     // replace it
@@ -86,22 +105,36 @@ public static boolean solveSudoku(int[][] board, int n) {
         return false;
     }
 
+    /**
+     * Prints the current state of the Sudoku board in a readable format.
+     * Each row is printed on a new line, with numbers separated by spaces.
+     *
+     * @param board The current state of the Sudoku board.
+     * @param n     The size of the Sudoku board (typically 9 for a standard puzzle).
+     */
     public static void print(int[][] board, int n) {
-        // We got the answer, just print it
+        // Print the board in a 9x9 grid format
         for (int r = 0; r < n; r++) {
             for (int d = 0; d < n; d++) {
                 System.out.print(board[r][d]);
                 System.out.print(" ");
             }
             System.out.print("\n");
 
+            // Print a blank line after every 3 rows for readability
             if ((r + 1) % (int) Math.sqrt(n) == 0) {
                 System.out.print("");
             }
         }
     }
 
-    // Driver Code
+    /**
+     * The driver method to demonstrate solving a Sudoku puzzle.
+     * A sample 9x9 Sudoku puzzle is provided, and the program attempts to solve it
+     * using the `solveSudoku` method. If a solution is found, it is printed to the console.
+     *
+     * @param args Command-line arguments (not used in this program).
+     */
     public static void main(String[] args) {
         int[][] board = new int[][] {
             {3, 0, 6, 5, 0, 8, 4, 0, 0},
@@ -117,7 +150,6 @@ public static void main(String[] args) {
         int n = board.length;
 
         if (solveSudoku(board, n)) {
-            // print solution
             print(board, n);
         } else {
             System.out.println("No solution");