Enhance docs, add tests in StackArrayList (#6020)

Author: Hardvan

src/main/java/com/thealgorithms/datastructures/stacks/StackArrayList.java

@@ -4,23 +4,41 @@
 import java.util.EmptyStackException;
 
 /**
- * This class implements a Stack using an ArrayList.
+ * A stack implementation backed by an {@link ArrayList}, offering dynamic resizing
+ * and LIFO (Last-In-First-Out) behavior.
  *
- * @param <T> the type of elements in this stack
+ * <p>The stack grows dynamically as elements are added, and elements are removed
+ * in reverse order of their addition.
+ *
+ * @param <T> the type of elements stored in this stack
  */
 public class StackArrayList<T> implements Stack<T> {
 
     private final ArrayList<T> stack;
 
+    /**
+     * Constructs an empty stack.
+     */
     public StackArrayList() {
         stack = new ArrayList<>();
     }
 
+    /**
+     * Adds an element to the top of the stack.
+     *
+     * @param value the element to be added
+     */
     @Override
     public void push(T value) {
         stack.add(value);
     }
 
+    /**
+     * Removes and returns the element from the top of the stack.
+     *
+     * @return the element removed from the top of the stack
+     * @throws EmptyStackException if the stack is empty
+     */
     @Override
     public T pop() {
         if (isEmpty()) {
@@ -29,6 +47,12 @@ public T pop() {
         return stack.removeLast();
     }
 
+    /**
+     * Returns the element at the top of the stack without removing it.
+     *
+     * @return the top element of the stack
+     * @throws EmptyStackException if the stack is empty
+     */
     @Override
     public T peek() {
         if (isEmpty()) {
@@ -37,16 +61,29 @@ public T peek() {
         return stack.getLast();
     }
 
+    /**
+     * Checks if the stack is empty.
+     *
+     * @return {@code true} if the stack is empty, {@code false} otherwise
+     */
     @Override
     public boolean isEmpty() {
         return stack.isEmpty();
     }
 
+    /**
+     * Empties the stack, removing all elements.
+     */
     @Override
     public void makeEmpty() {
         stack.clear();
     }
 
+    /**
+     * Returns the number of elements in the stack.
+     *
+     * @return the current size of the stack
+     */
     @Override
     public int size() {
         return stack.size();

src/test/java/com/thealgorithms/datastructures/stacks/StackArrayListTest.java

@@ -30,18 +30,18 @@ void testPeek() {
         stack.push(10);
         stack.push(20);
 
-        Assertions.assertEquals(20, stack.peek());
-        stack.pop(); // Remove 20
-        Assertions.assertEquals(10, stack.peek());
+        Assertions.assertEquals(20, stack.peek()); // Peek should return the top element
+        stack.pop(); // Remove top element
+        Assertions.assertEquals(10, stack.peek()); // Peek should now return the new top element
     }
 
     @Test
     void testIsEmpty() {
-        Assertions.assertTrue(stack.isEmpty());
+        Assertions.assertTrue(stack.isEmpty()); // Stack should initially be empty
         stack.push(1);
-        Assertions.assertFalse(stack.isEmpty());
+        Assertions.assertFalse(stack.isEmpty()); // After pushing, stack should not be empty
         stack.pop();
-        Assertions.assertTrue(stack.isEmpty());
+        Assertions.assertTrue(stack.isEmpty()); // After popping, stack should be empty again
     }
 
     @Test
@@ -50,27 +50,58 @@ void testMakeEmpty() {
         stack.push(2);
         stack.push(3);
         stack.makeEmpty();
-        Assertions.assertTrue(stack.isEmpty());
-        Assertions.assertEquals(0, stack.size());
+        Assertions.assertTrue(stack.isEmpty()); // Stack should be empty after makeEmpty is called
+        Assertions.assertEquals(0, stack.size()); // Size should be 0 after makeEmpty
     }
 
     @Test
     void testSize() {
-        Assertions.assertEquals(0, stack.size());
+        Assertions.assertEquals(0, stack.size()); // Initial size should be 0
         stack.push(1);
         stack.push(2);
-        Assertions.assertEquals(2, stack.size());
+        Assertions.assertEquals(2, stack.size()); // Size should reflect number of elements added
         stack.pop();
-        Assertions.assertEquals(1, stack.size());
+        Assertions.assertEquals(1, stack.size()); // Size should decrease with elements removed
     }
 
     @Test
     void testPopEmptyStackThrowsException() {
-        Assertions.assertThrows(EmptyStackException.class, stack::pop);
+        Assertions.assertThrows(EmptyStackException.class, stack::pop); // Popping from an empty stack should throw an exception
     }
 
     @Test
     void testPeekEmptyStackThrowsException() {
-        Assertions.assertThrows(EmptyStackException.class, stack::peek);
+        Assertions.assertThrows(EmptyStackException.class, stack::peek); // Peeking into an empty stack should throw an exception
+    }
+
+    @Test
+    void testMixedOperations() {
+        // Testing a mix of push, pop, peek, and size operations in sequence
+        stack.push(5);
+        stack.push(10);
+        stack.push(15);
+
+        Assertions.assertEquals(3, stack.size()); // Size should reflect number of elements
+        Assertions.assertEquals(15, stack.peek()); // Peek should show last element added
+
+        stack.pop(); // Remove top element
+        Assertions.assertEquals(10, stack.peek()); // New top should be 10
+        Assertions.assertEquals(2, stack.size()); // Size should reflect removal
+
+        stack.push(20); // Add a new element
+        Assertions.assertEquals(20, stack.peek()); // Top should be the last added element
+    }
+
+    @Test
+    void testMultipleMakeEmptyCalls() {
+        // Ensures calling makeEmpty multiple times does not throw errors or misbehave
+        stack.push(1);
+        stack.push(2);
+        stack.makeEmpty();
+        Assertions.assertTrue(stack.isEmpty());
+
+        stack.makeEmpty();
+        Assertions.assertTrue(stack.isEmpty());
+        Assertions.assertEquals(0, stack.size());
     }
 }