Enhance docs, remove main, add tests in StackArray (#6019)

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

@@ -1,7 +1,13 @@
 package com.thealgorithms.datastructures.stacks;
 
 /**
- * This class implements a Stack using a regular array.
+ * Implements a generic stack using an array.
+ *
+ * <p>This stack automatically resizes when necessary, growing to accommodate additional elements and
+ * shrinking to conserve memory when its size significantly decreases.
+ *
+ * <p>Elements are pushed and popped in LIFO (last-in, first-out) order, where the last element added
+ * is the first to be removed.
  *
  * @param <T> the type of elements in this stack
  */
@@ -13,11 +19,20 @@ public class StackArray<T> implements Stack<T> {
     private T[] stackArray;
     private int top;
 
+    /**
+     * Creates a stack with a default capacity.
+     */
     @SuppressWarnings("unchecked")
     public StackArray() {
         this(DEFAULT_CAPACITY);
     }
 
+    /**
+     * Creates a stack with a specified initial capacity.
+     *
+     * @param size the initial capacity of the stack, must be greater than 0
+     * @throws IllegalArgumentException if size is less than or equal to 0
+     */
     @SuppressWarnings("unchecked")
     public StackArray(int size) {
         if (size <= 0) {
@@ -28,6 +43,11 @@ public class StackArray<T> implements Stack<T> {
         this.top = -1;
     }
 
+    /**
+     * Pushes an element onto the top of the stack. Resizes the stack if it is full.
+     *
+     * @param value the element to push
+     */
     @Override
     public void push(T value) {
         if (isFull()) {
@@ -36,6 +56,13 @@ public class StackArray<T> implements Stack<T> {
         stackArray[++top] = value;
     }
 
+    /**
+     * Removes and returns the element from the top of the stack. Shrinks the stack if
+     * its size is below a quarter of its capacity, but not below the default capacity.
+     *
+     * @return the element removed from the top of the stack
+     * @throws IllegalStateException if the stack is empty
+     */
     @Override
     public T pop() {
         if (isEmpty()) {
@@ -48,6 +75,12 @@ public class StackArray<T> implements Stack<T> {
         return value;
     }
 
+    /**
+     * Returns the element at the top of the stack without removing it.
+     *
+     * @return the top element of the stack
+     * @throws IllegalStateException if the stack is empty
+     */
     @Override
     public T peek() {
         if (isEmpty()) {
@@ -56,6 +89,11 @@ public class StackArray<T> implements Stack<T> {
         return stackArray[top];
     }
 
+    /**
+     * Resizes the internal array to a new capacity.
+     *
+     * @param newSize the new size of the stack array
+     */
     private void resize(int newSize) {
         @SuppressWarnings("unchecked") T[] newArray = (T[]) new Object[newSize];
         System.arraycopy(stackArray, 0, newArray, 0, top + 1);
@@ -63,21 +101,60 @@ public class StackArray<T> implements Stack<T> {
         maxSize = newSize;
     }
 
+    /**
+     * Checks if the stack is full.
+     *
+     * @return true if the stack is full, false otherwise
+     */
     public boolean isFull() {
         return top + 1 == maxSize;
     }
 
+    /**
+     * Checks if the stack is empty.
+     *
+     * @return true if the stack is empty, false otherwise
+     */
     @Override
     public boolean isEmpty() {
         return top == -1;
     }
 
-    @Override public void makeEmpty() { // Doesn't delete elements in the array but if you call
-        top = -1; // push method after calling makeEmpty it will overwrite previous values
+    /**
+     * Empties the stack, marking it as empty without deleting elements. Elements are
+     * overwritten on subsequent pushes.
+     */
+    @Override
+    public void makeEmpty() {
+        top = -1;
     }
 
+    /**
+     * Returns the number of elements currently in the stack.
+     *
+     * @return the size of the stack
+     */
     @Override
     public int size() {
         return top + 1;
     }
+
+    /**
+     * Returns a string representation of the stack.
+     *
+     * @return a string representation of the stack
+     */
+    @Override
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append("StackArray [");
+        for (int i = 0; i <= top; i++) {
+            sb.append(stackArray[i]);
+            if (i < top) {
+                sb.append(", ");
+            }
+        }
+        sb.append("]");
+        return sb.toString();
+    }
 }