Enhance docs, add tests in LeftistHeap (#5982)

src/main/java/com/thealgorithms/datastructures/heaps/LeftistHeap.java

@@ -2,24 +2,33 @@ package com.thealgorithms.datastructures.heaps;
 
 import java.util.ArrayList;
 
-/*
- * This is a leftist heap that follows the same operations as a
- * binary min heap, but may be unbalanced at times and follows a
- * leftist property, in which the left side is more heavy on the
- * right based on the null-path length (npl) values.
+/**
+ * This class implements a Leftist Heap, which is a type of priority queue
+ * that follows similar operations to a binary min-heap but allows for
+ * unbalanced structures based on the leftist property.
  *
- * Source: https://iq.opengenus.org/leftist-heap/
+ * <p>
+ * A Leftist Heap maintains the leftist property, which ensures that the
+ * left subtree is heavier than the right subtree based on the
+ * null-path length (npl) values. This allows for efficient merging
+ * of heaps and supports operations like insertion, extraction of
+ * the minimum element, and in-order traversal.
+ * </p>
  *
+ * <p>
+ * For more information on Leftist Heaps, visit:
+ * <a href="https://iq.opengenus.org/leftist-heap/">OpenGenus</a>
+ * </p>
  */
-
 public class LeftistHeap {
+    // Node class representing each element in the Leftist Heap
     private static final class Node {
         private final int element;
         private int npl;
         private Node left;
         private Node right;
 
-        // Node constructor setting the data element and left/right pointers to null
+        // Node constructor that initializes the element and sets child pointers to null
         private Node(int element) {
             this.element = element;
             left = null;
@@ -30,31 +39,45 @@ public class LeftistHeap {
 
     private Node root;
 
-    // Constructor
+    // Constructor initializing an empty Leftist Heap
     public LeftistHeap() {
         root = null;
     }
 
-    // Checks if heap is empty
+    /**
+     * Checks if the heap is empty.
+     *
+     * @return true if the heap is empty; false otherwise
+     */
     public boolean isEmpty() {
         return root == null;
     }
 
-    // Resets structure to initial state
+    /**
+     * Resets the heap to its initial state, effectively clearing all elements.
+     */
     public void clear() {
-        // We will put head is null
-        root = null;
+        root = null; // Set root to null to clear the heap
     }
 
-    // Merge function that merges the contents of another leftist heap with the
-    // current one
+    /**
+     * Merges the contents of another Leftist Heap into this one.
+     *
+     * @param h1 the LeftistHeap to be merged into this heap
+     */
     public void merge(LeftistHeap h1) {
-        // If the present function is rhs then we ignore the merge
+        // Merge the current heap with the provided heap and set the provided heap's root to null
         root = merge(root, h1.root);
         h1.root = null;
     }
 
-    // Function merge with two Nodes a and b
+    /**
+     * Merges two nodes, maintaining the leftist property.
+     *
+     * @param a the first node
+     * @param b the second node
+     * @return the merged node maintaining the leftist property
+     */
     public Node merge(Node a, Node b) {
         if (a == null) {
             return b;
@@ -64,17 +87,17 @@ public class LeftistHeap {
             return a;
         }
 
-        // Violates leftist property, so must do a swap
+        // Ensure that the leftist property is maintained
         if (a.element > b.element) {
             Node temp = a;
             a = b;
             b = temp;
         }
 
-        // Now we call the function merge to merge a and b
+        // Merge the right child of node a with node b
         a.right = merge(a.right, b);
 
-        // Violates leftist property so must swap here
+        // If left child is null, make right child the left child
         if (a.left == null) {
             a.left = a.right;
             a.right = null;
@@ -89,14 +112,21 @@ public class LeftistHeap {
         return a;
     }
 
-    // Function insert. Uses the merge function to add the data
+    /**
+     * Inserts a new element into the Leftist Heap.
+     *
+     * @param a the element to be inserted
+     */
     public void insert(int a) {
         root = merge(new Node(a), root);
     }
 
-    // Returns and removes the minimum element in the heap
+    /**
+     * Extracts and removes the minimum element from the heap.
+     *
+     * @return the minimum element in the heap, or -1 if the heap is empty
+     */
     public int extractMin() {
-        // If is empty return -1
         if (isEmpty()) {
             return -1;
         }
@@ -106,14 +136,23 @@ public class LeftistHeap {
         return min;
     }
 
-    // Function returning a list of an in order traversal of the data structure
+    /**
+     * Returns a list of the elements in the heap in in-order traversal.
+     *
+     * @return an ArrayList containing the elements in in-order
+     */
     public ArrayList<Integer> inOrder() {
         ArrayList<Integer> lst = new ArrayList<>();
         inOrderAux(root, lst);
         return new ArrayList<>(lst);
     }
 
-    // Auxiliary function for in_order
+    /**
+     * Auxiliary function for in-order traversal
+     *
+     * @param n the current node
+     * @param lst the list to store the elements in in-order
+     */
     private void inOrderAux(Node n, ArrayList<Integer> lst) {
         if (n == null) {
             return;