Improve class & function documentation in HighestSetBit.java

Author: Hardvan

src/main/java/com/thealgorithms/bitmanipulation/HighestSetBit.java

@@ -1,32 +1,56 @@
 package com.thealgorithms.bitmanipulation;
+
 import java.util.Optional;
 
 /**
  * Find Highest Set Bit
- * This class provides a function calculating the position (or index)
- * of the most significant bit being set to 1 in a given integer.
- * @author Bama Charan Chhandogi (https://github.com/BamaCharanChhandogi)
+ *
+ * This class provides a utility method to calculate the position of the highest 
+ * (most significant) bit that is set to 1 in a given non-negative integer. 
+ * It is often used in bit manipulation tasks to find the left-most set bit in binary 
+ * representation of a number.
+ *
+ * Example: 
+ * - For input 18 (binary 10010), the highest set bit is at position 4 (zero-based index).
+ * 
+ * @author Bama Charan Chhandogi
+ * @version 1.0
+ * @since 2021-06-23
  */
-
 public final class HighestSetBit {
+
     private HighestSetBit() {
     }
 
+    /**
+     * Finds the highest (most significant) set bit in the given integer.
+     * The method returns the position (index) of the highest set bit as an {@link Optional}.
+     *
+     * - If the number is 0, no bits are set, and the method returns {@link Optional#empty()}.
+     * - If the number is negative, the method throws {@link IllegalArgumentException}.
+     *
+     * @param num The input integer for which the highest set bit is to be found. It must be non-negative.
+     * @return An {@link Optional} containing the index of the highest set bit (zero-based). 
+     *         Returns {@link Optional#empty()} if the number is 0.
+     * @throws IllegalArgumentException if the input number is negative.
+     */
     public static Optional<Integer> findHighestSetBit(int num) {
         if (num < 0) {
             throw new IllegalArgumentException("Input cannot be negative");
         }
 
         if (num == 0) {
-            return Optional.empty();
+            return Optional.empty(); // No bits are set in 0
         }
 
         int position = 0;
+
+        // Right-shift the number until it becomes zero, counting the number of shifts
         while (num > 0) {
             num >>= 1;
             position++;
         }
 
-        return Optional.of(position - 1);
+        return Optional.of(position - 1); // Subtract 1 to convert to zero-based index
     }
 }