Merge pull request #4 from bcExpt1123/coderabbitai/docstrings/9534874

📝 Add docstrings to `test`

Author: bcExpt1123

src/main/java/org/alda/Main.java

@@ -32,6 +32,13 @@
 public class Main {
     private static final Scanner scanner = new Scanner(System.in);
 
+    /**
+     * Launches the interactive console application for demonstrating various data structures.
+     *
+     * Displays a main menu allowing users to select and explore different data structure categories, each with its own submenu and test demonstrations. The application continues running until the user chooses to exit.
+     *
+     * @param args command-line arguments (not used)
+     */
     public static void main(String[] args) {
         boolean running = true;
 
@@ -52,6 +59,9 @@ public static void main(String[] args) {
         }
         scanner.close();
     }
+    /**
+     * Displays the main menu options for selecting a data structure category or exiting the program.
+     */
     private static void displayMainMenu() {
         System.out.println("\n=== Data Structure Demonstration ===");
         System.out.println("1. Linked Lists");
@@ -62,6 +72,11 @@ private static void displayMainMenu() {
         System.out.print("\nEnter your choice (1-5): ");
     }
 
+    /**
+     * Displays a submenu for selecting and testing different types of linked lists.
+     *
+     * Loops until the user chooses to return to the main menu. For each selection, runs the corresponding linked list demonstration and waits for user input before returning to the submenu.
+     */
     private static void linkedListMenu() {
         while (true) {
             System.out.println("\n=== Linked List Types ===");
@@ -88,6 +103,11 @@ private static void linkedListMenu() {
         }
     }
 
+    /**
+     * Displays an interactive submenu for selecting and testing different stack implementations.
+     *
+     * Allows the user to choose between array-based and linked list-based stacks, runs the corresponding test demonstration, and returns to the main menu upon request.
+     */
     private static void stackMenu() {
         while (true) {
             System.out.println("\n=== Stack Types ===");
@@ -108,6 +128,12 @@ private static void stackMenu() {
         }
     }
 
+    /**
+     * Displays an interactive submenu for selecting and testing different queue implementations.
+     *
+     * Presents options for simple queue, array-based queue, linked list-based queue, and priority queue.
+     * Executes the corresponding test method based on user selection and waits for user input before returning to the submenu.
+     */
     private static void queueMenu() {
         while (true) {
             System.out.println("\n=== Queue Types ===");
@@ -132,6 +158,11 @@ private static void queueMenu() {
         }
     }
 
+    /**
+     * Displays a submenu for tree data structure demonstrations and runs the selected test.
+     *
+     * Presents options for Binary Search Tree and AVL Tree, executes the corresponding test method based on user input, and waits for user confirmation before returning.
+     */
     private static void treeMenu() {
         System.out.println("\n=== Tree Types ===");
         System.out.println("1. Binary Search Tree");
@@ -149,6 +180,12 @@ private static void treeMenu() {
         pressEnterToContinue();
     }
 
+    /**
+     * Prompts the user to enter a menu choice and returns a valid integer within the specified range.
+     *
+     * @param max the maximum valid menu option (inclusive)
+     * @return the user's validated menu choice as an integer between 1 and {@code max}
+     */
     private static int getMenuChoice(int max) {
         while (true) {
             try {
@@ -163,11 +200,19 @@ private static int getMenuChoice(int max) {
         }
     }
 
+    /**
+     * Prompts the user to press Enter and waits for input before continuing.
+     */
     private static void pressEnterToContinue() {
         System.out.print("\nPress Enter to continue...");
         scanner.nextLine();
     }
 
+    /**
+     * Demonstrates basic operations on a simple linked list of integers, including appending, inserting, deleting, printing, and searching for elements.
+     *
+     * Initializes a simple linked list, performs a sequence of modifications, prints the list and head node, and displays search results for specific values.
+     */
     public static void testSimpleLinkedList() {
         System.out.println("\n=== Initialize Simple Linked List ===");
         ISimpleLinkedList<Integer> intList = new SimpleLinkedList<Integer>();
@@ -195,6 +240,11 @@ public static void testSimpleLinkedList() {
         System.out.println("Search for 5: " + intList.search(5));
     }
 
+    /**
+     * Demonstrates basic operations on a doubly linked list of integers.
+     *
+     * Initializes a doubly linked list, appends several integer values, and prints the list in forward order.
+     */
     public static void testDoublyLinkedList() {
         System.out.println("\n=== Initialize Doubly Linked List ===");
         DoublyLinkedList<Integer> intList = new DoublyLinkedList<Integer>();
@@ -209,6 +259,11 @@ public static void testDoublyLinkedList() {
         intList.print();
     }
 
+    /**
+     * Demonstrates basic operations on a circular linked list of integers.
+     *
+     * Initializes a circular linked list, appends several integer values, and prints the list contents.
+     */
     public static void testCircularLinkedList() {
         System.out.println("\n=== Initialize Circular Linked List ===");
         CircularLinkedList<Integer> intList = new CircularLinkedList<Integer>();
@@ -223,6 +278,11 @@ public static void testCircularLinkedList() {
         intList.print();
     }
 
+    /**
+     * Demonstrates the usage of a sorted linked list by inserting integers in non-sorted order and printing the sorted result.
+     *
+     * Initializes a sorted linked list, inserts several integer values using sorted insertion, and prints the list to show the maintained order.
+     */
     public static void testSortedLinkedList() {
         System.out.println("\n=== Initialize Sorted Linked List ===");
         ISortedLinkedList<Integer> intList = new SortedLinkedList<Integer>();
@@ -238,6 +298,11 @@ public static void testSortedLinkedList() {
         intList.print();
     }
 
+    /**
+     * Demonstrates basic operations on a doubly ended linked list (deque) of integers.
+     *
+     * Initializes a doubly ended list, performs a sequence of insertions at both the front and end, and prints the resulting list.
+     */
     public static void testDoublyEndedList(){
         System.out.println("\n=== Initialize Doubly Ended Linked List ===");
         IDoublyEndedList<Integer> intList = new DoublyEndedList<>();
@@ -255,6 +320,11 @@ public static void testDoublyEndedList(){
         intList.print();
     }
 
+    /**
+     * Demonstrates basic operations on an array-based stack of integers.
+     *
+     * Initializes a stack, pushes several values, then performs pop and peek operations while printing the results.
+     */
     public static void testStackArray(){
         System.out.println("\n=== Initialize Stack Array ===");
         IStackArray<Integer> intStack = new StackArray<>();
@@ -269,6 +339,11 @@ public static void testStackArray(){
         System.out.println("Pop: " + intStack.pop());
     }
 
+    /**
+     * Demonstrates stack operations using a linked list implementation.
+     *
+     * Initializes a linked list-based stack, performs push, pop, and peek operations, and prints the results to the console.
+     */
     public static void testStackLinkedList(){
         System.out.println("\n=== Initialize Stack Linked List ===");
         IStackLinkedList<Integer> intStack = new StackLinkedList<>();
@@ -283,6 +358,11 @@ public static void testStackLinkedList(){
         System.out.println("Pop: " + intStack.pop());
     }
 
+    /**
+     * Demonstrates basic queue operations including enqueue, dequeue, and retrieving front and rear elements.
+     *
+     * Initializes a queue of integers, enqueues several values, dequeues three elements, and prints the results along with the current front and rear values.
+     */
     public static void testQueue(){
         System.out.println("\n=== Initialize Queue ===");
         IQueue<Integer> intQueue = new Queue<>();
@@ -308,6 +388,11 @@ public static void testQueue(){
         System.out.println("Rear: " + rear);
     }
 
+    /**
+     * Demonstrates the usage of an array-based queue by performing enqueue, dequeue, and inspection operations.
+     *
+     * Initializes an integer queue, enqueues several elements, dequeues three elements, and prints the dequeued values along with the current front and rear elements.
+     */
     public static void testQueueArray(){
         System.out.println("\n=== Initialize Queue Array ===");
         IQueue<Integer> intQueue = new QueueArray<>();
@@ -333,6 +418,11 @@ public static void testQueueArray(){
         System.out.println("Rear: " + rear);
     }
 
+    /**
+     * Demonstrates the usage of a linked list-based queue by performing enqueue, dequeue, and inspection operations.
+     *
+     * Initializes a queue, enqueues several integers, dequeues multiple elements, and prints the results along with the current front and rear elements.
+     */
     public static void testQueueLinkedList(){
         System.out.println("\n=== Initialize Queue Linked List ===");
         IQueue<Integer> intQueue = new QueueLinkedList<>();
@@ -358,6 +448,11 @@ public static void testQueueLinkedList(){
         System.out.println("Rear: " + rear);
     }
 
+    /**
+     * Demonstrates the usage of a priority queue by enqueuing integer elements with specified priorities and dequeuing several elements to show priority-based removal order.
+     *
+     * This method initializes a priority queue, enqueues multiple integers with associated priorities, then dequeues and prints four elements to illustrate how the queue prioritizes elements.
+     */
     public static void testPriorityQueue(){
         System.out.println("\n=== Initialize Priority Queue ===");
         IPriorityQueue<Integer> intQueue = new PriorityQueue<>();
@@ -386,6 +481,12 @@ public static void testPriorityQueue(){
         System.out.println("Dequeue: " + item3);
     }
 
+    /**
+     * Demonstrates basic operations on a binary search tree, including insertion, inorder traversal, and search.
+     *
+     * Initializes a binary search tree of integers, inserts several values, prints the inorder traversal,
+     * and searches for the value 4, displaying whether it is found.
+     */
     public static void testBST(){
         System.out.println("\n=== Initialize Binary Search Tree ===");
         BinarySearchTree<Integer> bst = new BinarySearchTree<>();
@@ -406,6 +507,11 @@ public static void testBST(){
         else System.out.println("false");
     }
 
+    /**
+     * Demonstrates insertion of multiple integers into an AVL tree.
+     *
+     * Initializes an AVL tree and inserts the values 10, 20, 30, 40, 50, and 25 to showcase automatic balancing during insertion.
+     */
     public static void testAVL(){
         AVL<Integer> avl = new AVL<>();
         AVL.Node<Integer> root = null;

src/main/java/org/alda/structure/linkedList/circular/CircularLinkedList.java

@@ -63,8 +63,8 @@ public void append(T data) {
     }
 
     /**
-     * Prints the data stored in each node of the circular linked list.
-     * The traversal stops when the list has looped back to the head.
+     * Prints the data of each node in the circular linked list in sequence, starting from the head.
+     * Traversal continues until the list loops back to the head node or if the list is empty.
      */
     public void print() {
         Node<T> current = head;

src/main/java/org/alda/structure/linkedList/circular/Node.java

@@ -49,8 +49,9 @@ public Node(T data) {
     }
 
     /**
-     * Prints the data stored in this node and, if present, the data in the next node.
-     * The output format is: {@code Data: <data>, Next: <next data>}
+     * Prints this node's data and, if available, the data of the next node to standard output.
+     *
+     * The output begins with a newline and follows the format: {@code Data: <data>, Next: <next data>}.
      */
     public void print() {
         System.out.print("\nData: " + data);

src/main/java/org/alda/structure/linkedList/deque/DoublyEndedList.java

@@ -68,8 +68,7 @@ public void setTail(Node<T> tail) {
     }
 
     /**
-     * Prints the contents of the list.
-     * Each node's data is printed, followed by a new line.
+     * Prints the data of each node in the list from head to tail.
      */
     public void print() {
         Node<T> current = head;

src/main/java/org/alda/structure/linkedList/deque/Node.java

@@ -52,8 +52,10 @@ public Node(){
     }
 
     /**
-     * Prints the data stored in this node, and if present, the data in the next and previous nodes.
-     * The output format is: {@code Data: <data>, Next: <next data>, Prev: <previous data>}
+     * Prints this node's data, along with the data of adjacent nodes if available, to standard output.
+     *
+     * The output includes the node's data, and, if present, the data of the next and previous nodes in the format:
+     * {@code Data: <data>, Next: <next data>, Prev: <previous data>}.
      */
     public void print(){
         System.out.print("\nData: " + data);

src/main/java/org/alda/structure/linkedList/doubly/DoublyLinkedList.java

@@ -78,8 +78,7 @@ public void prepend(T data) {
     }
 
     /**
-     * Prints the data stored in each node of the doubly linked list from head to tail.
-     * Each node's data is printed along with the data in its next and previous nodes, if available.
+     * Prints each node's data in the list from head to tail, including adjacent nodes' data if present.
      */
     public void print() {
         Node<T> current = head;

src/main/java/org/alda/structure/linkedList/doubly/Node.java

@@ -44,8 +44,11 @@ public Node(final T data) {
     }
 
     /**
-     * Prints the data stored in this node, as well as the data in the next and previous nodes, if available.
-     * The output format is: {@code Data: <data>, Next: <next data>, Prev: <prev data>}
+     * Prints this node's data, along with the data of adjacent nodes if they exist.
+     *
+     * The output begins with a newline and follows the format:
+     * {@code Data: <data>, Next: <next data>, Prev: <prev data>}.
+     * The "Next" and "Prev" fields are included only if the corresponding nodes are present.
      */
     public void print() {
         System.out.print("\nData: " + data);

src/main/java/org/alda/structure/linkedList/simple/Node.java

@@ -37,8 +37,9 @@ public Node(T data) {
     }
 
     /**
-     * Prints the data stored in this node and, if present, the data in the next node.
-     * The output format is: {@code Data: <data>, Next: <next data>}
+     * Prints the data of this node, and if a next node exists, also prints its data.
+     *
+     * The output is formatted as: {@code Data: <data>, Next: <next data>}, with a preceding newline.
      */
     public void print() {
         System.out.print("\nData: " + data);

src/main/java/org/alda/structure/linkedList/simple/SimpleLinkedList.java

@@ -136,7 +136,7 @@ public void setHead(Node<T> head) {
     }
 
     /**
-     * Prints the data stored in each node of the linked list from head to tail.
+     * Outputs the data of each node in the linked list sequentially from head to tail.
      */
     public void print() {
         Node<T> current = head;

src/main/java/org/alda/structure/tree/bst/Node.java

@@ -10,12 +10,22 @@ public class Node<T> implements Printable {
     T key;
     Node<T> left;
     Node<T> right;
+    /**
+     * Constructs a new node with the specified key and no child nodes.
+     *
+     * @param key the value to store in this node
+     */
     public Node(T key){
         this.key = key;
         left = null;
         right = null;
     }
 
+    /**
+     * Prints the node's key and the keys of its left and right children, if present, to the standard output.
+     *
+     * The output format is: "Data: [key], Left: [left.key], Right: [right.key]". Child information is omitted if the respective child is null.
+     */
     public void print() {
         System.out.print("\nData: " + key);
         if (left != null) {