Enhance docs, add more tests in Bag (#5947)

src/main/java/com/thealgorithms/datastructures/bags/Bag.java

@@ -4,14 +4,18 @@ import java.util.Iterator;
 import java.util.NoSuchElementException;
 
 /**
- * A collection that allows adding and iterating over elements but does not support element removal.
+ * A generic collection that allows adding and iterating over elements but does not support
+ * element removal. This class implements a simple bag data structure, which can hold duplicate
+ * elements and provides operations to check for membership and the size of the collection.
+ *
+ * <p>Bag is not thread-safe and should not be accessed by multiple threads concurrently.
  *
  * @param <E> the type of elements in this bag
  */
 public class Bag<E> implements Iterable<E> {
 
-    private Node<E> firstElement; // First element in the bag
-    private int size; // Number of elements in the bag
+    private Node<E> firstElement; // Reference to the first element in the bag
+    private int size; // Count of elements in the bag
 
     // Node class representing each element in the bag
     private static final class Node<E> {
@@ -21,6 +25,7 @@ public class Bag<E> implements Iterable<E> {
 
     /**
      * Constructs an empty bag.
+     * <p>This initializes the bag with zero elements.
      */
     public Bag() {
         firstElement = null;
@@ -30,7 +35,7 @@ public class Bag<E> implements Iterable<E> {
     /**
      * Checks if the bag is empty.
      *
-     * @return true if the bag is empty, false otherwise
+     * @return {@code true} if the bag contains no elements; {@code false} otherwise
      */
     public boolean isEmpty() {
         return size == 0;
@@ -39,7 +44,7 @@ public class Bag<E> implements Iterable<E> {
     /**
      * Returns the number of elements in the bag.
      *
-     * @return the number of elements
+     * @return the number of elements currently in the bag
      */
     public int size() {
         return size;
@@ -48,7 +53,10 @@ public class Bag<E> implements Iterable<E> {
     /**
      * Adds an element to the bag.
      *
-     * @param element the element to add
+     * <p>This method adds the specified element to the bag. Duplicates are allowed, and the
+     * bag will maintain the order in which elements are added.
+     *
+     * @param element the element to add; must not be {@code null}
      */
     public void add(E element) {
         Node<E> newNode = new Node<>();
@@ -61,8 +69,10 @@ public class Bag<E> implements Iterable<E> {
     /**
      * Checks if the bag contains a specific element.
      *
-     * @param element the element to check for
-     * @return true if the bag contains the element, false otherwise
+     * <p>This method uses the {@code equals} method of the element to determine membership.
+     *
+     * @param element the element to check for; must not be {@code null}
+     * @return {@code true} if the bag contains the specified element; {@code false} otherwise
      */
     public boolean contains(E element) {
         for (E value : this) {
@@ -76,6 +86,8 @@ public class Bag<E> implements Iterable<E> {
     /**
      * Returns an iterator over the elements in this bag.
      *
+     * <p>The iterator provides a way to traverse the elements in the order they were added.
+     *
      * @return an iterator that iterates over the elements in the bag
      */
     @Override
@@ -88,19 +100,35 @@ public class Bag<E> implements Iterable<E> {
 
         private Node<E> currentElement;
 
+        /**
+         * Constructs a ListIterator starting from the given first element.
+         *
+         * @param firstElement the first element of the bag to iterate over
+         */
         ListIterator(Node<E> firstElement) {
             this.currentElement = firstElement;
         }
 
+        /**
+         * Checks if there are more elements to iterate over.
+         *
+         * @return {@code true} if there are more elements; {@code false} otherwise
+         */
         @Override
         public boolean hasNext() {
             return currentElement != null;
         }
 
+        /**
+         * Returns the next element in the iteration.
+         *
+         * @return the next element in the bag
+         * @throws NoSuchElementException if there are no more elements to return
+         */
         @Override
         public E next() {
             if (!hasNext()) {
-                throw new NoSuchElementException();
+                throw new NoSuchElementException("No more elements in the bag.");
             }
             E element = currentElement.content;
             currentElement = currentElement.nextElement;